@bongos/core 1.19.899 → 1.19.901

package/tests/idea_task_descent.mjs

@@ -0,0 +1,347 @@
+// tests/idea_task_descent.mjs
+//
+// task 1004086 (BV2.R07, goal 1000095) — task→task descent edges. ADR 0312.
+//
+// WHAT IS ASSERTED HERE, AND WHY IT IS DB-FREE. The parts of this feature that
+// can go wrong silently are JavaScript, not SQL: the cycle refusal, the
+// breadth-first de-duplication, and the derivation that turns three existing
+// signals into edges. A cycle does not render oddly — the payout (R09) and the
+// descent (R10) both walk this graph, so a cycle fails to terminate. A merge
+// makes the graph a DAG rather than a tree, so a task reachable by two paths
+// must be counted ONCE at its SHORTEST depth, or the same origin is paid twice
+// for one descendant.
+//
+// The client is injected (every reader and writer takes { client }), so those
+// paths run for real against a recorded query log rather than being simulated.
+// A real-Postgres suite would SELF-SKIP on this machine, and a skipped test
+// prints ok and counts as passed — which is how a green lane hides what never
+// ran. The DDL half is therefore asserted as a SOURCE invariant instead.
+//
+// Run:  node tests/idea_task_descent.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const descent = require('../modules/ideas/descent.js');
+
+const MIGRATION = path.join(ROOT, 'modules/ideas/migrations/ideas_007_task_descent_edges.sql');
+const DDL = fs.readFileSync(MIGRATION, 'utf8');
+const MANIFEST = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/ideas/module.json'), 'utf8'));
+const WRITER_SRC = fs.readFileSync(path.join(ROOT, 'modules/ideas/pollers/descent-writer.js'), 'utf8');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed += 1; console.log('ok   ' + name); })
+    .catch((e) => { failed += 1; console.log('FAIL ' + name + '\n     ' + (e && (e.message || JSON.stringify(e)))); });
+}
+
+// A client that answers each query from a queue, recording what it was asked.
+function fakeClient(queue) {
+  const log = [];
+  return {
+    log,
+    query: async (text, params) => { log.push({ text, params }); return { rows: queue.shift() ?? [] }; },
+  };
+}
+
+// A client that answers the BFS from a real adjacency map, so the walk is
+// exercised as a walk rather than against canned rows.
+function graphClient(edges) {
+  // edges: [{ task_id, parent_task_id, relation }]
+  const log = [];
+  return {
+    log,
+    query: async (text, params) => {
+      log.push({ text, params });
+      if (!Array.isArray(params[0])) return { rows: [] };   // the INSERT, not a walk
+      const frontier = params[0].map(Number);
+      const up = /parent_task_id AS id/.test(text);
+      const rows = edges
+        .filter((e) => frontier.includes(Number(up ? e.task_id : e.parent_task_id)))
+        // from_id is what the real statements select, and what lets one query
+        // answer several roots at once — the fake must carry it or the batched
+        // walk would be exercised against a shape production never returns.
+        .map((e) => ({
+          id: up ? e.parent_task_id : e.task_id,
+          from_id: up ? e.task_id : e.parent_task_id,
+          relation: e.relation,
+        }));
+      return { rows };
+    },
+  };
+}
+
+// ── the migration ───────────────────────────────────────────────────────────
+
+await test('the migration declares the COMPOSITE key — one edge per (task, parent) pair', () => {
+  assert.match(DDL, /PRIMARY KEY \(task_id, parent_task_id\)/,
+    'the key must be the pair: a merge gives a task several parents');
+});
+
+await test('the migration refuses a SELF-EDGE in the schema', () => {
+  assert.match(DDL, /CHECK \(task_id <> parent_task_id\)/);
+  assert.match(DDL, /ideas_task_descent_no_self_edge/);
+});
+
+await test('the migration indexes the PARENT direction — the descent walk', () => {
+  assert.match(DDL, /CREATE INDEX IF NOT EXISTS idx_ideas_task_descent_parent/);
+});
+
+await test('the migration is additive and namespaced (ADR 0083 §5)', () => {
+  assert.doesNotMatch(DDL, /DROP TABLE|TRUNCATE|DROP COLUMN/i,
+    'a module migration may not carry destructive DDL');
+  for (const m of DDL.matchAll(/CREATE (?:TABLE|INDEX)(?: IF NOT EXISTS)? (\w+)/g)) {
+    assert.ok(m[1].startsWith('ideas_') || m[1].startsWith('idx_ideas_'),
+      `object ${m[1]} is outside the ideas_ namespace`);
+  }
+});
+
+await test('the migration proves its own effect — the safety net is present', () => {
+  assert.match(DDL, /RAISE EXCEPTION/,
+    'the ideas_003/005/006 precedent: a migration that cannot prove its effect must not report success');
+});
+
+// ── the writer ──────────────────────────────────────────────────────────────
+
+await test('a SELF-EDGE is refused before any query is issued', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(7, 7, 'rewrite', { client: c }),
+    (e) => e.code === 'DESCENT_SELF_EDGE'
+  );
+  assert.equal(c.log.length, 0, 'the self case must not reach the database at all');
+});
+
+await test('a LONGER CYCLE is refused — the walk would not terminate', async () => {
+  // 9 already descends from 5 (5 → 9), so making 5 descend from 9 closes a loop.
+  const c = graphClient([{ task_id: 9, parent_task_id: 5, relation: 'split' }]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 9, 'merge', { client: c }),
+    (e) => e.code === 'DESCENT_CYCLE'
+  );
+  assert.ok(
+    c.log.every((q) => !/INSERT/i.test(q.text)),
+    'the cycle must be refused BEFORE the row is written'
+  );
+});
+
+await test('a cycle DEEPER than the default bound is still refused', async () => {
+  // A chain 5 → 6 → … → 80, far past DESCENT_MAX_DEPTH (64). The closing edge
+  // is the one that matters, because it is the one that would get written.
+  const chain = [];
+  for (let i = 5; i < 80; i += 1) chain.push({ task_id: i + 1, parent_task_id: i, relation: 'split' });
+  const c = graphClient(chain);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 80, 'merge', { client: c }),
+    (e) => e.code === 'DESCENT_CYCLE'
+  );
+});
+
+await test('an unknown relation is refused by NAME, not by a constraint violation', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 9, 'inspired-by', { client: c }),
+    (e) => e.code === 'DESCENT_BAD_RELATION' && e.allowed.includes('cascade')
+  );
+  assert.equal(c.log.length, 0);
+});
+
+await test('a legitimate edge IS written, and upserts on the pair', async () => {
+  const c = graphClient([]);
+  await descent.linkTaskDescent(5, 9, 'split', { client: c });
+  const ins = c.log.find((q) => /INSERT INTO ideas_task_descent/i.test(q.text));
+  assert.ok(ins, 'the edge must be inserted');
+  assert.match(ins.text, /ON CONFLICT \(task_id, parent_task_id\) DO UPDATE/,
+    'the derivation runs on every ship, so the write must be idempotent');
+  assert.deepEqual(ins.params, [5, 9, 'split']);
+});
+
+await test('a non-numeric id is refused rather than passed to SQL', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent('abc', 9, 'split', { client: c }),
+    (e) => e.code === 'DESCENT_BAD_ID'
+  );
+  assert.equal(c.log.length, 0);
+});
+
+// ── the walk ────────────────────────────────────────────────────────────────
+
+await test('a task reachable TWICE is returned ONCE, at its SHORTEST depth', async () => {
+  // The DAG a merge produces: 1 → 2 → 4 and 1 → 3 → 4, plus the short edge
+  // 1 → 4. Node 4 is reachable at depth 1 and depth 2; the payout must decay by
+  // the shorter one, and must not pay twice.
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 3, parent_task_id: 1, relation: 'split' },
+    { task_id: 4, parent_task_id: 2, relation: 'merge' },
+    { task_id: 4, parent_task_id: 3, relation: 'merge' },
+    { task_id: 4, parent_task_id: 1, relation: 'cascade' },
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  const ids = got.map((r) => Number(r.id));
+  assert.deepEqual(ids, [2, 3, 4], 'each node once, nearest first');
+  assert.equal(got.find((r) => Number(r.id) === 4).depth, 1, 'shortest path wins');
+});
+
+await test('a node is EXPANDED at most once — the convergent DAG does not blow up', async () => {
+  // Same shape, one level deeper. A recursive CTE re-expands every path; this
+  // asserts the walk does not, by counting the queries it issues: one per
+  // LEVEL, never one per path.
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 3, parent_task_id: 1, relation: 'split' },
+    { task_id: 4, parent_task_id: 2, relation: 'merge' },
+    { task_id: 4, parent_task_id: 3, relation: 'merge' },
+    { task_id: 5, parent_task_id: 4, relation: 'split' },
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  assert.deepEqual(got.map((r) => Number(r.id)), [2, 3, 4, 5]);
+  // One query per LEVEL — {1}, {2,3}, {4}, {5} — with the last returning
+  // nothing and ending the walk. Four queries for a graph carrying several
+  // distinct paths through node 4: the count tracks DEPTH, not the number of
+  // paths, which is exactly what a recursive CTE cannot promise.
+  assert.equal(c.log.length, 4, `one query per level, got ${c.log.length}`);
+});
+
+await test('a CYCLE in the stored data cannot hang the walk', async () => {
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 1, parent_task_id: 2, relation: 'merge' },   // the loop
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  assert.deepEqual(got.map((r) => Number(r.id)), [2], 'the start is never revisited');
+});
+
+await test('both directions walk the same way', async () => {
+  const c = graphClient([
+    { task_id: 9, parent_task_id: 5, relation: 'split' },
+    { task_id: 12, parent_task_id: 9, relation: 'rewrite' },
+  ]);
+  const up = await descent.ancestorsOfTask(12, { client: c });
+  assert.deepEqual(up.map((r) => Number(r.id)), [9, 5]);
+  assert.deepEqual(up.map((r) => r.depth), [1, 2], 'depth is the hop count the payout decays by');
+});
+
+// ── the derivation ──────────────────────────────────────────────────────────
+
+await test('a CASCADE task derives its edge from the id inside source_ref', async () => {
+  // The key itself contains dashes, so the id is the trailing numeric run.
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-artist-review-on-ship-1003583',
+    parent_task_id: null, folded_in: null,
+  }]]);
+  const edges = await descent.deriveEdgesForTask(900, { client: c });
+  assert.deepEqual(edges, [{ parent: 1003583, relation: 'cascade' }]);
+});
+
+await test('a SPLIT derives from parent_task_id, and a FOLD from merged_into', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'manual', source_ref: null,
+    parent_task_id: 500, folded_in: [401, 402],
+  }]]);
+  const edges = await descent.deriveEdgesForTask(900, { client: c });
+  assert.deepEqual(edges, [
+    { parent: 500, relation: 'split' },
+    { parent: 401, relation: 'fold' },
+    { parent: 402, relation: 'fold' },
+  ]);
+});
+
+await test('a task with no derivation signal produces NO edges', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'manual', source_ref: null, parent_task_id: null, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('a source_ref that is not a cascade id yields nothing, not a NaN edge', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-some-key-with-no-id',
+    parent_task_id: null, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('a self-referential signal is filtered out before it is written', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-k-900',
+    parent_task_id: 900, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('syncDescentForTask REPORTS a refusal instead of throwing', async () => {
+  // A ship must never break because a provenance edge was refused.
+  const c = {
+    log: [],
+    query: async (text, params) => {
+      c.log.push({ text, params });
+      if (/FROM tasks t/.test(text)) {
+        return { rows: [{ id: 5, source: 'manual', source_ref: null, parent_task_id: 9, folded_in: null }] };
+      }
+      // The cycle probe: 9 already descends from 5.
+      if (/parent_task_id = ANY/.test(text)) return { rows: [{ id: 9, from_id: 5, relation: 'split' }] };
+      return { rows: [] };
+    },
+  };
+  const res = await descent.syncDescentForTask(5, { client: c });
+  assert.equal(res.written.length, 0);
+  assert.equal(res.skipped.length, 1);
+  assert.equal(res.skipped[0].code, 'DESCENT_CYCLE');
+});
+
+// ── the production call path ────────────────────────────────────────────────
+
+await test('the module DECLARES the poller, or nothing ever runs it', () => {
+  assert.ok(MANIFEST.contributes.pollers?.includes('descent-writer'),
+    'a poller file with no manifest entry is a silent no-op (ADR 0289)');
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/ideas/pollers/descent-writer.js')),
+    'and a declared seam whose artifact is absent is the same no-op in reverse');
+});
+
+await test('the writer subscribes to task.shipped and cannot double-subscribe', () => {
+  assert.match(WRITER_SRC, /api\.on\('task\.shipped'|EVENT = 'task\.shipped'/);
+  assert.match(WRITER_SRC, /if \(_off\) return;/,
+    'a reloaded loader must not accumulate listeners and derive every ship twice');
+});
+
+await test('the writer uses APIs the doorway actually publishes', () => {
+  // The first cut guessed `api.log.child(...)`, which does not exist on
+  // src/module-api.js. The optional-chaining fallback meant it silently
+  // degraded to `console` instead of failing, so nothing caught it — the
+  // shape of bug a static read finds and a green suite does not.
+  const doorway = require(path.join(ROOT, "src/module-api.js"));
+  for (const m of WRITER_SRC.matchAll(/\bapi\.([A-Za-z_$][\w$]*)/g)) {
+    assert.ok(m[1] in doorway,
+      `the writer calls api.${m[1]}, which the published doorway does not export`);
+  }
+});
+
+await test('the writer reads the task id the way the event actually carries it', () => {
+  // task.shipped hands the subscriber the TASK ROW — the same subject
+  // modules/agents/pollers/event-router.js receives as `task`. Guarding
+  // against payload shapes that never occur reads as uncertainty about the
+  // contract.
+  assert.doesNotMatch(WRITER_SRC, /payload\.task_id|payload\.task\b/,
+    "speculative payload shapes: the event carries the task row");
+});
+await test('the handler swallows its own failure — a reactor must not break the actor', async () => {
+  const writer = require('../modules/ideas/pollers/descent-writer.js');
+  // No client injected, so syncDescentForTask reaches the real pool and throws.
+  // The handler must still resolve.
+  await writer.onShipped({ id: 999999999 });
+  await writer.onShipped({});          // no id at all
+  await writer.onShipped(null);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);