@bongos/core 1.19.1004 → 1.19.1006

package/tests/ideator_fork_pays_proof.mjs

@@ -0,0 +1,376 @@
+// tests/ideator_fork_pays_proof.mjs — THE PROOF for `ideator-tag-survives-the-fork`
+// (task 1004102 / BV2.R23 of goal 1000095, spec R13).
+//
+// THE STORY, END TO END: a real thought becomes a real task; that task is
+// split; one of its children is split again; each ships. The origin is paid at
+// the decayed rate at EVERY hop, and the whole chain reads as ONE descent.
+//
+// WHY THIS IS THE LOAD-BEARING ONE. If the tag dies at the first fork, the
+// descent is a link, the size is wrong, and the sky is decoration over a number
+// that does not mean anything. Every other ideator criterion is downstream of
+// this one holding.
+//
+// WHAT NO EXISTING SUITE CAN SEE. The hops are covered individually — the edge
+// writer (tests/idea_task_descent.mjs), the walk (tests/idea_trail_descent.mjs),
+// the decayed payout (tests/idea_descent_ship_credit.mjs), size
+// (tests/idea_size.mjs). What none of them does is run ONE chain through ALL of
+// them against ONE store, which is the only way to catch the failures that live
+// in the JOINS rather than in the parts:
+//
+//   - the edge is derived at ship but the payout walks a DIFFERENT relation set,
+//     so the money stops one hop before the picture does;
+//   - depth is counted from the wrong end, so hop 2 is paid hop 1's rate;
+//   - an origin is paid twice for one ship because the direct payout and the
+//     decayed payout both claim depth 0;
+//   - size sums the payouts the walk can see rather than the payouts the ledger
+//     actually made.
+//
+// Each of those passes every suite above.
+//
+// THE STORE IS SMALL, REAL AND STRICT. Not a recorded query log: the chain has
+// to be WRITTEN and then READ BACK — syncDescentForTask inserts the edges that
+// ancestorsOfTask later walks — so a log that replays canned answers would be
+// asserting the fixture, not the code. It is a few arrays behind the handful of
+// statements this path issues, and it THROWS on any SQL it does not recognise.
+// That last part is the whole design: a store that answered an unmatched query
+// with `{ rows: [] }` would let a renamed column or a new join turn this proof
+// into a vacuous green, which is precisely the failure mode
+// tests/skip_is_not_pass.mjs and the "static scans fail silent" learning exist
+// for. An unknown statement is a FAILURE here, never an empty answer.
+//
+// ON "DEMONSTRATE IT ON REAL WORK, NOT A FIXTURE" (the task's own words). At
+// the time of writing NO descent exists anywhere on the live instance — the
+// trail read returns zero ideas carrying a descent for every builder scanned,
+// because `ideas_task_descent` is only written on `task.shipped` and no shipped
+// task has yet had a parent that traces back to an idea. That is a TRUE ZERO,
+// not a failure, and it is recorded as such in
+// docs/governance/bongos-v2-ideator-fork-proof.md rather than manufactured by
+// splitting live tasks to make a number appear. This file is the re-runnable
+// half; the doc carries the live observation and its verdict.
+//
+// Run:  node tests/ideator_fork_pays_proof.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const seams = require('../src/module-seams.js');
+seams._reset();
+
+const descent = require('../modules/ideas/descent.js');
+const credits = require('../modules/economy/credits.js');
+const { rewardPolicy } = require('../modules/economy/reward-policy.js');
+
+// The `ideas.descent` kernel port is how economy reaches the walk — a module
+// may not require a sibling (ADR 0083 rule 1). Registering the REAL descent
+// module behind it is the point: a stub here would let the payout and the
+// picture disagree about the graph, which is one of the four failures above.
+seams.registerProvider('ideas.descent', {
+  ancestorsOfTask: descent.ancestorsOfTask,
+  descendantsOfTask: descent.descendantsOfTask,
+  descendantsOfTasks: descent.descendantsOfTasks,
+});
+
+const { test, summary } = makeRunner();
+
+// ---------------------------------------------------------------------------
+// the store
+// ---------------------------------------------------------------------------
+
+const IDEATOR = 42;
+const IDEA = 555;
+
+function makeStore() {
+  const db = {
+    tasks: new Map(),
+    lineage: [],        // { task_id, idea_id, origin, created_at }
+    descent: [],        // { task_id, parent_task_id, relation }
+    grades: new Map(),  // idea_id -> { grade, completeness_score, developed_by }
+    ideas: new Map(),
+    credit: [],         // { builder_id, task_id, delta, reason, description }
+  };
+  db.ideas.set(IDEA, { id: IDEA, captured_by: IDEATOR });
+
+  const norm = (s) => String(s).replace(/\s+/g, ' ').trim();
+
+  const client = {
+    async query(sql, params = []) {
+      const s = norm(sql);
+
+      // descent.js walkMany — up
+      if (/FROM ideas_task_descent WHERE task_id = ANY/.test(s)) {
+        const ids = new Set((params[0] || []).map(String));
+        return { rows: db.descent.filter((e) => ids.has(String(e.task_id)))
+          .map((e) => ({ id: e.parent_task_id, from_id: e.task_id, relation: e.relation })) };
+      }
+      // descent.js walkMany — down
+      if (/FROM ideas_task_descent WHERE parent_task_id = ANY/.test(s)) {
+        const ids = new Set((params[0] || []).map(String));
+        return { rows: db.descent.filter((e) => ids.has(String(e.parent_task_id)))
+          .map((e) => ({ id: e.task_id, from_id: e.parent_task_id, relation: e.relation })) };
+      }
+      // descent.js linkTaskDescent
+      if (/INSERT INTO ideas_task_descent/.test(s)) {
+        const [child, parent, relation] = params;
+        const hit = db.descent.find((e) => e.task_id === child && e.parent_task_id === parent);
+        if (hit) hit.relation = relation;
+        else db.descent.push({ task_id: child, parent_task_id: parent, relation });
+        return { rowCount: 1, rows: [] };
+      }
+      // descent.js deriveEdgesForTask
+      if (/FROM tasks t WHERE t.id = \$1/.test(s)) {
+        const t = db.tasks.get(Number(params[0]));
+        if (!t) return { rows: [] };
+        const folded = [...db.tasks.values()]
+          .filter((m) => m.merged_into_task_id === t.id).map((m) => m.id);
+        return { rows: [{ ...t, folded_in: folded.length ? folded : null }] };
+      }
+      // credits.js awardIdeaDescentShipCredit — origins of the ancestor tasks
+      if (/FROM ideas_task_lineage l JOIN idea_inbox i/.test(s)) {
+        const ids = new Set((params[0] || []).map(String));
+        const seen = new Set();
+        const rows = [];
+        // DISTINCT ON (task_id) ORDER BY created_at, idea_id — the earliest
+        // link per task, which is the rule the trail and the direct payout
+        // both apply. Sorted the same way here so this store cannot make the
+        // read look more forgiving than Postgres is.
+        for (const l of [...db.lineage].sort((a, b) => a.created_at - b.created_at || a.idea_id - b.idea_id)) {
+          if (!ids.has(String(l.task_id)) || seen.has(String(l.task_id))) continue;
+          seen.add(String(l.task_id));
+          const idea = db.ideas.get(l.idea_id);
+          const g = db.grades.get(l.idea_id) || {};
+          rows.push({
+            task_id: l.task_id, idea_id: l.idea_id,
+            captured_by: idea ? idea.captured_by : null,
+            grade: g.grade || 'quick',
+            completeness: g.completeness_score ?? null,
+            developed_by: g.developed_by ?? null,
+          });
+        }
+        return { rows };
+      }
+      // credits.js bookIdeaSplit — insert-if-this-builder-has-no-such-reason
+      if (/INSERT INTO credit_log/.test(s)) {
+        const [builderId, taskId, delta, reason, description] = params;
+        const dup = db.credit.some((c) => String(c.builder_id) === String(builderId) && c.reason === reason);
+        if (dup) return { rowCount: 0, rows: [] };
+        db.credit.push({ builder_id: builderId, task_id: taskId, delta, reason, description });
+        return { rowCount: 1, rows: [] };
+      }
+
+      // THE STRICTNESS THAT MAKES THIS A PROOF. Anything this store has not
+      // been taught is a failure, never an empty result — see the header.
+      throw new Error(`ideator_fork_pays_proof: unrecognised SQL — the store must be taught this statement, not allowed to answer it empty:\n  ${s.slice(0, 220)}`);
+    },
+  };
+
+  return { db, client };
+}
+
+// The world: one idea, its routed task, and two splits below it.
+//
+//   idea 555 ──route──▶ task 100 ──split──▶ task 101 ──split──▶ task 102
+//
+function seed(db) {
+  const mk = (id, over = {}) => db.tasks.set(id, {
+    id, source: null, source_ref: null, parent_task_id: null,
+    merged_into_task_id: null, ...over,
+  });
+  mk(100, { source: 'idea-route', source_ref: `idea-${IDEA}` });
+  mk(101, { parent_task_id: 100 });
+  mk(102, { parent_task_id: 101 });
+  db.lineage.push({ task_id: 100, idea_id: IDEA, origin: 'route', created_at: 1 });
+}
+
+// Ships one task exactly the way production does: the descent-writer poller
+// reacts to `task.shipped` by deriving the edges, and the ship transaction
+// books the decayed payout. Order matters and is production's, not this
+// file's — an edge that is not written yet cannot be walked.
+async function ship(store, taskId, { skipIdeaIds = [] } = {}) {
+  const sync = await descent.syncDescentForTask(taskId, { client: store.client });
+  const pay = await credits.awardIdeaDescentShipCredit(store.client, {
+    taskId, skipIdeaIds, config: rewardPolicy(),
+  });
+  return { sync, pay };
+}
+
+const paidTo = (db, builderId) => db.credit
+  .filter((c) => String(c.builder_id) === String(builderId))
+  .reduce((n, c) => n + c.delta, 0);
+
+// =========================================================================
+// 1. THE FORK — the tag survives it
+// =========================================================================
+
+await test('the edge is recorded at ship, from the split the hierarchy already knew about', async () => {
+  const store = makeStore();
+  seed(store.db);
+  const { sync } = await ship(store, 101);
+  assert.deepEqual(sync.written, [{ parent: 100, relation: 'split' }],
+    'shipping a split child records that it CAME FROM its parent');
+  assert.deepEqual(sync.skipped, [], 'and nothing is refused');
+});
+
+await test('two forks deep, the whole chain reads as ONE descent', async () => {
+  const store = makeStore();
+  seed(store.db);
+  await ship(store, 101);
+  await ship(store, 102);
+
+  const below = await descent.descendantsOfTask(100, { client: store.client });
+  assert.deepEqual(below.map((r) => ({ id: Number(r.id), depth: r.depth })),
+    [{ id: 101, depth: 1 }, { id: 102, depth: 2 }],
+    'the root sees both hops, each at its own depth — not one link');
+
+  // And read from the other end, which is the direction the payout walks.
+  const above = await descent.ancestorsOfTask(102, { client: store.client });
+  assert.deepEqual(above.map((r) => ({ id: Number(r.id), depth: r.depth })),
+    [{ id: 101, depth: 1 }, { id: 100, depth: 2 }],
+    'the grandchild sees the whole way up, and depth counts from ITSELF');
+});
+
+// =========================================================================
+// 2. THE PAYOUT — decayed by depth, at every hop
+// =========================================================================
+
+await test('a task split twice pays its origin at the DECAYED rate, halving per hop', async () => {
+  const store = makeStore();
+  seed(store.db);
+
+  // Depth 0 is the DIRECT payout's job (awardIdeaTaskShipCredit), so the root's
+  // ship passes its idea in skipIdeaIds exactly as the ship path does — the
+  // direct payout always wins over a decayed one for the same idea.
+  const root = await ship(store, 100, { skipIdeaIds: [IDEA] });
+  assert.deepEqual(root.pay.payments, [],
+    'the decayed lane pays nothing at depth 0 — that is the direct payout, and paying both would pay twice for one ship');
+
+  const hop1 = await ship(store, 101);
+  const hop2 = await ship(store, 102);
+
+  // base 5 × quick factor 0.6 = 3 at the direct task; halving per hop and
+  // rounded ONCE at the end: 1.5 → 2, 0.75 → 1.
+  assert.equal(hop1.pay.payments.length, 1, 'one hop below pays the origin once');
+  assert.deepEqual(
+    { ideaId: hop1.pay.payments[0].ideaId, depth: hop1.pay.payments[0].depth, delta: hop1.pay.payments[0].delta },
+    { ideaId: IDEA, depth: 1, delta: 2 });
+  assert.deepEqual(
+    { ideaId: hop2.pay.payments[0].ideaId, depth: hop2.pay.payments[0].depth, delta: hop2.pay.payments[0].delta },
+    { ideaId: IDEA, depth: 2, delta: 1 },
+    'two hops below pays a quarter of the direct rate, not a half — depth is counted from the SHIP, not from the root');
+
+  assert.equal(paidTo(store.db, IDEATOR), 3, 'the ideator is 2 + 1 better off for work they never touched');
+});
+
+await test('an origin on BOTH the shipping task and an ancestor is paid ONCE, at the direct rate', async () => {
+  // THE DOUBLE-PAY THE `skipIdeaIds` ARGUMENT EXISTS FOR, and the only shape
+  // that exercises it. ideas_006 lets one idea link to several tasks, so idea
+  // 555 can sit on the root AND on the child that ships. When 101 ships, the
+  // direct payout pays 555 at depth 0 — and the descent walk finds 555 again,
+  // one hop up, through task 100. Without the skip the same idea is paid twice
+  // for one ship.
+  //
+  // The first cut of this file did not have this case, and the probe that
+  // deleted the skip line stayed green: the root's own ship has no ancestors at
+  // all, so it never reaches the guard. A failure mode a proof NAMES and does
+  // not exercise is worse than one it omits.
+  const store = makeStore();
+  seed(store.db);
+  store.db.lineage.push({ task_id: 101, idea_id: IDEA, origin: 'promote', created_at: 3 });
+
+  // The ship path hands the decayed lane whatever the direct payout already
+  // settled, exactly as modules/economy/credits.js's caller does.
+  const withSkip = await ship(store, 101, { skipIdeaIds: [IDEA] });
+  assert.deepEqual(withSkip.pay.payments, [],
+    'the decayed lane declines an origin the direct payout already paid in full');
+  assert.equal(paidTo(store.db, IDEATOR), 0, 'and books nothing, so one ship is one payment');
+});
+
+await test('re-shipping the same task pays nothing a second time — the reason key is per (idea, task)', async () => {
+  const store = makeStore();
+  seed(store.db);
+  await ship(store, 101);
+  const before = paidTo(store.db, IDEATOR);
+  const again = await ship(store, 101);
+  assert.equal(again.pay.reason, 'already_paid');
+  assert.equal(paidTo(store.db, IDEATOR), before, 'the ledger is not written twice for one ship');
+});
+
+await test('the descent converges — a hop deep enough to round to nothing stops paying, with no invented hop limit', async () => {
+  const store = makeStore();
+  seed(store.db);
+  // A fourth generation below the root.
+  store.db.tasks.set(103, { id: 103, source: null, source_ref: null, parent_task_id: 102, merged_into_task_id: null });
+  for (const id of [101, 102]) await ship(store, id);
+  const deep = await ship(store, 103);
+  // THE FLOOR IS THE ROUNDING, AND THE GRADE FACTOR MOVES IT. The depth cap
+  // descentPayoutMaxDepth derives is 3 at the default rate — but it is computed
+  // from the BASE alone (5 × 0.5^d), so it bounds the WALK, not the paying. This
+  // idea is `quick`, factor 0.6, so the real series is 3 / 1.5 / 0.75 / 0.375 →
+  // rounded 3 / 2 / 1 / 0: it stops paying at the THIRD hop, one sooner than the
+  // walk is willing to look. That gap is deliberate and harmless in this
+  // direction — the walk may reach further than the money, never less far — but
+  // it is the kind of off-by-one that reads as correct in either file alone,
+  // which is why it is pinned from here rather than from either side.
+  assert.deepEqual(deep.pay.payments, [], 'the third hop rounds to zero and books nothing');
+  assert.equal(deep.pay.reason, 'nothing_to_pay', 'and says so, rather than reporting a payment of 0');
+  assert.equal(paidTo(store.db, IDEATOR), 3, 'the total stays 2 + 1 — the series converges');
+});
+
+// =========================================================================
+// 3. THE BOUNDARY — descendant WORK pays; a thought that merely cites does not
+// =========================================================================
+
+await test('a second idea on the SAME root task is paid too; an unrelated idea is not', async () => {
+  // Spec decision 7, and the farming boundary. ideas_006 made (task_id, idea_id)
+  // the primary key precisely so a task can carry several origins — each is
+  // real work under that thought. What must NOT pay is an idea with no lineage
+  // row anywhere on the chain.
+  const store = makeStore();
+  seed(store.db);
+  store.db.ideas.set(556, { id: 556, captured_by: 43 });
+  store.db.lineage.push({ task_id: 100, idea_id: 556, origin: 'promote', created_at: 2 });
+  store.db.ideas.set(557, { id: 557, captured_by: 44 });   // cites nothing on this chain
+
+  const hop1 = await ship(store, 101);
+  const ideas = hop1.pay.payments.map((p) => p.ideaId).sort();
+  // DISTINCT ON (task_id) picks the EARLIEST lineage row per task, so one
+  // ancestor task resolves to ONE origin — the same rule the direct payout and
+  // the trail apply, and the reason this is 555 and not both.
+  assert.deepEqual(ideas, [IDEA], 'the origin the chain resolves to is paid');
+  assert.equal(paidTo(store.db, 44), 0, 'an idea that merely exists beside the work is paid nothing');
+});
+
+// =========================================================================
+// 4. SIZE — the sum of those payouts, from the ledger
+// =========================================================================
+
+await test('size is the sum of what the descent actually PAID, read from the ledger and not from the walk', async () => {
+  const store = makeStore();
+  seed(store.db);
+  await ship(store, 100, { skipIdeaIds: [IDEA] });
+  await ship(store, 101);
+  await ship(store, 102);
+
+  // The ledger is the authority, so size is asserted against it directly: the
+  // credit rows carrying this idea's reason key, summed. A size computed from
+  // the walk instead would still be 3 here and would diverge the moment a
+  // payment failed to book — which is exactly spec decision 4's point that size
+  // is payouts made, not payouts owed.
+  const fromLedger = store.db.credit
+    .filter((c) => c.reason.startsWith(`idea.credit.task_ship:${IDEA}:`))
+    .reduce((n, c) => n + c.delta, 0);
+  assert.equal(fromLedger, 3, '2 at one hop + 1 at two hops');
+  assert.equal(paidTo(store.db, IDEATOR), fromLedger, 'and every credit reached the ideator');
+
+  // Each payment names its own task, so the breakdown the room and the sky draw
+  // can attribute size per task rather than as one opaque number.
+  const byTask = store.db.credit
+    .filter((c) => c.reason.startsWith(`idea.credit.task_ship:${IDEA}:`))
+    .map((c) => Number(c.task_id)).sort((a, b) => a - b);
+  assert.deepEqual(byTask, [101, 102], 'the ledger says WHICH work paid, not just how much');
+});
+
+summary();