@bongos/core 1.19.900 → 1.19.902

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.900'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.902'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/helpers.mjs

@@ -72,6 +72,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { execFileSync } from 'node:child_process';
+import vm from 'node:vm';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -495,3 +496,139 @@ export function shallowCloneReason(root = ROOT) {
   return 'shallow clone — full history is unavailable here, so this case cannot be evaluated '
     + '(git fetch --unshallow to run it)';
 }
+
+// bootProfilePage — boot the REAL modules/hall-ui/public/profile.js in a vm
+// against a stub DOM and a stub OTBKit, and hand back what it RENDERED plus
+// every request it made.
+//
+// Shared because two suites now assert on that HTML rather than on the data
+// behind it: tests/profile_activity.mjs (the four idea outcomes, task 1003281)
+// and tests/idea_trail_descent.mjs (the descent under them, task 1004089). The
+// second exists BECAUSE the first finding inherited from the abandoned task
+// 1004054 was that the prior attempt tested the server-side builder only. A
+// second hand-copied harness would be a second thing to keep in step with a
+// page that changes, so the harness moved here and the fixture stayed with
+// each caller —  is the /inbox/by-builder/ payload to answer with.
+const PROFILE_JS = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/profile.js'), 'utf8');
+// Boot the REAL profile.js against a stub DOM + a stub OTBKit that captures each
+// ledger's rowHtml, and return what it rendered plus every request it made.
+export function bootProfilePage({ signedIn = true, trail = [] } = {}) {
+  const els = new Map();
+  const makeEl = () => ({
+    dataset: {}, style: {}, textContent: '', hidden: false, _html: '',
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; },
+    addEventListener() {},
+    querySelector() { return makeEl(); }, querySelectorAll() { return []; }, appendChild() {},
+    set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; },
+  });
+  const documentObj = {
+    title: '',
+    body: { dataset: { page: 'profile' } },
+    documentElement: { dataset: {}, style: {}, classList: { add() {}, remove() {} } },
+    getElementById(id) { if (!els.has(id)) els.set(id, makeEl()); return els.get(id); },
+    querySelector(sel) { return this.getElementById(String(sel).replace(/^#/, '')); },
+    querySelectorAll() { return []; },
+    createElement() { return makeEl(); },
+    addEventListener() {},
+  };
+
+  const requests = [];
+  const client = {
+    request: async (method, url) => {
+      requests.push(url);
+      if (url.endsWith('/me')) {
+        return signedIn
+          ? { status: 200, ok: true, data: { builder: { id: 95, rank: 'metic' } } }
+          : { status: 401, ok: false, data: null };
+      }
+      if (/\/builders\/\d+\/profile$/.test(url)) {
+        return { status: 200, ok: true, data: { builder: { id: 95, github_login: 'jaxri', rank: 'metic' }, shipped_count: 4, achievements: [], recent_ships: [] } };
+      }
+      if (url.includes('/activity?')) {
+        const isGoals = url.includes('section=goals');
+        return { status: 200, ok: true, data: { rows: isGoals ? [{ id: 7, title: 'A goal', disciplines: ['artist'], task_shipped: 1, task_total: 2 }] : [{ id: 42, title: 'A work', discipline: 'engineer', shipped_at: '2026-08-01T00:00:00Z' }], total: 1 } };
+      }
+      if (url.includes('/inbox/by-builder/')) {
+        return { status: 200, ok: true, data: { ideas: trail, total: trail.length } };
+      }
+      return { status: 404, ok: false, data: null };
+    },
+  };
+
+  // The captured ledgers, keyed by the mount element they were given.
+  const ledgers = new Map();
+  let tabsOnChange = null;
+  const kit = {
+    makePager: (prefix, key, opts = {}) => ({
+      prefix, key, page: 1, perPage: opts.defaultPerPage || 25,
+      perPageOptions: [10, 25], minPerPage: opts.minPerPage ?? 10,
+    }),
+    pageOffset: (p) => Math.max(0, (p.page - 1) * p.perPage),
+    makeLedger: ({ mount, rowHtml }) => {
+      const rec = { rows: [], total: 0, html: '' };
+      const ledger = {
+        render(rows, opts = {}) {
+          rec.rows = rows || [];
+          rec.total = opts.total || 0;
+          rec.html = rec.rows.map((r, i) => rowHtml(r, i)).join('');
+        },
+      };
+      ledgers.set(mount, rec);
+      return ledger;
+    },
+    makeTabs: ({ tabs, onChange }) => {
+      let current = tabs[0].id;
+      tabsOnChange = onChange;
+      onChange(current);
+      return { active: () => current, activate(id) { current = id; onChange(id); } };
+    },
+    shipVisualThumbHtml: () => '',
+  };
+
+  const windowObj = {
+    __BRANDING__: {}, __MODULES__: { enabled: {} },
+    BongosClient: { createClient: () => client },
+    OTBKit: kit,
+    OTB: {
+      // task 1003936 — the role axis vocabulary (dom-utils OTB.role*). PRESENT for
+      // the same reason categoryChip is: an undefined helper throws mid-render.
+      roleAxisLabel: () => 'Role',
+      roleLabel: (d) => (!d ? '' : d === 'unclassified' ? 'No role yet' : d === 'ui' ? 'UI' : d.charAt(0).toUpperCase() + d.slice(1)),
+      roleOptions: () => [{ value: '', label: '— any —' }, { value: 'engineer', label: 'Engineer' }, { value: 'artist', label: 'Artist' }],
+      roleIsUnset: (d) => !d || d === 'unclassified',
+      ROLE_UNSET: 'unclassified',
+      escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+      $: (sel) => documentObj.querySelector(sel),
+      fmtNum: (n) => String(n ?? 0),
+      fmtDate: (iso) => String(iso ?? '').slice(0, 10),
+      rankLabel: (r) => r,
+      toast() {},
+    },
+    location: { hostname: 'builders.cloudbongos.com', search: '', pathname: '/profile' },
+    localStorage: { getItem: () => null, setItem() {} },
+    addEventListener() {},
+  };
+
+  const sandbox = {
+    window: windowObj, document: documentObj, location: windowObj.location,
+    console, setTimeout, clearTimeout, URLSearchParams,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(PROFILE_JS, sandbox, { filename: 'profile.js' });
+
+  const htmlFor = (mountId) => {
+    const rec = ledgers.get(documentObj.getElementById(mountId));
+    return rec ? rec.html : null;
+  };
+  return {
+    requests,
+    htmlFor,
+    switchCraft: (id) => { if (tabsOnChange) tabsOnChange(id); },
+    el: (id) => documentObj.getElementById(id),
+  };
+}
+
+// One microtask turn — profile.js boots through a chain of awaits.
+export const settle = () => new Promise((r) => setTimeout(r, 0));

package/tests/idea_descent_ship_credit.mjs

@@ -0,0 +1,481 @@
+// tests/idea_descent_ship_credit.mjs
+//
+// task 1004088 (BV2.R09, goal 1000095) — the ideator payout follows the
+// task→task descent and decays by depth. ADR 0312; spec
+// docs/specs/bongos-v2-ideator-surface.md decisions 6, 7 and 16.
+//
+// WHY THIS FILE IS SHARP. This is money. The failure modes are all silent —
+// nothing renders wrong, nobody sees an error, an origin is simply paid the
+// wrong amount or paid twice:
+//
+//   * PAID TWICE. A merge makes the descent a DAG, so one origin can sit above
+//     a shipping task by two routes of different length, and two ancestor tasks
+//     can share one source idea. Each of those is a duplicate payment that
+//     looks exactly like a correct one in the ledger.
+//   * FARMED. Spec decision 7 draws the line at descendant WORK: a separate
+//     thought that merely cites an origin must not pay it. The descent surface
+//     deliberately displays MORE than the payout counts, so the payout path has
+//     to be provably free of idea→idea relations.
+//   * DRIFTED. The direct payout and this one must agree about what an idea's
+//     work is worth before depth, or the same idea pays differently depending
+//     on which hop the ship happened at.
+//   * DIVERGED FROM TODAY. "Existing first-hop behaviour preserved" is a
+//     done-when, so the no-port and no-ancestor paths must be provably inert.
+//
+// DB-free: the client is a stub whose credit_log is a set of reasons and whose
+// lineage SELECT answers from a fixture, and the descent port is registered
+// with a stub walk — so the decay arithmetic, the de-duplication and the
+// idempotency are proven without a Postgres. A real-Postgres suite would
+// SELF-SKIP on a machine with no database, and a skipped case prints ok and
+// counts as passed.
+//
+// Run:  node tests/idea_descent_ship_credit.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 credits = require('../modules/economy/credits.js');
+const api = require('../src/module-api.js');
+const { rewardPolicy, IDEA_DESCENT_DECAY } = require('../modules/economy/reward-policy.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed += 1; console.log(`ok   ${name}`); }
+  catch (err) { failed += 1; console.log(`FAIL ${name}\n     ${err && (err.message || JSON.stringify(err))}`); }
+}
+
+// ---------------------------------------------------------------------------
+// the harness
+// ---------------------------------------------------------------------------
+
+// The `ideas.descent` port is SINGLE-PROVIDER and has no unregister (a port is
+// a required capability, not a last-write-wins slot — src/module-seams.js). So
+// the stub walk is registered exactly once, and each test varies what it
+// returns rather than re-registering. The one case that needs the port ABSENT
+// runs first, before the registration below.
+let ancestorsFixture = [];
+function registerStubDescentPort() {
+  api.registerProvider('ideas.descent', {
+    ancestorsOfTask: async () => ancestorsFixture,
+  });
+}
+const withDescentPort = async (ancestors, fn) => {
+  ancestorsFixture = ancestors;
+  try { return await fn(); } finally { ancestorsFixture = []; }
+};
+
+// `lineage` maps an ancestor task id to the row the DISTINCT ON read returns.
+function stubClient(lineage = {}) {
+  const credited = [];
+  const log = [];
+  return {
+    credited,
+    log,
+    async query(sql, params) {
+      log.push({ sql, params });
+      if (/FROM ideas_task_lineage/i.test(sql)) {
+        const ids = (params[0] || []).map(String);
+        return { rows: ids.map((id) => lineage[id]).filter(Boolean) };
+      }
+      if (/INSERT INTO credit_log/i.test(sql)) {
+        // THE STUB MUST DEDUPE THE WAY THE REAL SQL DOES — on (builder_id,
+        // reason), not on reason alone. bookIdeaSplit books a SPLIT as two rows
+        // sharing one reason, so a reason-only stub refuses the second payee and
+        // reports a correct 70/30 split as a duplicate. That is a stub that
+        // manufactures a failure the database would not have, and it is exactly
+        // how a split-payee test gets written to the wrong expectation.
+        assert.match(sql, /builder_id = \$1 AND reason = \$4/,
+          'the real predicate is builder-scoped; this stub mirrors it, so pin it');
+        const reason = params[3];
+        const builderId = params[0];
+        if (credited.some((r) => r.reason === reason && String(r.builder_id) === String(builderId))) {
+          return { rowCount: 0, rows: [] };
+        }
+        credited.push({ builder_id: builderId, task_id: params[1], delta: params[2], reason });
+        return { rowCount: 1, rows: [] };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+const src = (taskId, ideaId, authorId, extra = {}) => ({
+  task_id: String(taskId), idea_id: ideaId, captured_by: authorId,
+  grade: 'quick', completeness: null, developed_by: null, ...extra,
+});
+
+const ON = rewardPolicy({});
+const BASE = credits.IDEA_TASK_SHIP_BASE;
+const QUICK = credits.QUICK_IDEA_FACTOR;
+
+// ---------------------------------------------------------------------------
+// 0. BEFORE the port exists — existing behaviour, preserved
+// ---------------------------------------------------------------------------
+
+// FIRST, and it has to be: a port is single-provider and cannot be unregistered,
+// so the only honest way to test the absent-provider path is to test it before
+// anything registers one.
+await test('with NO descent port, nothing is paid and nothing is asked of the database', async () => {
+  // An instance running without the ideas module still ships tasks, and its
+  // direct payout is untouched. This is what "existing first-hop behaviour
+  // preserved" means when the module is absent.
+  assert.equal(api.hasProvider('ideas.descent'), false, 'nothing has registered the port yet');
+  const c = stubClient({});
+  const r = await credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON });
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'no_descent_port');
+  assert.equal(c.log.length, 0, 'no query is issued at all');
+});
+
+registerStubDescentPort();
+
+// ---------------------------------------------------------------------------
+// 1. the decay
+// ---------------------------------------------------------------------------
+
+await test('a task ONE hop below an idea pays it the halved share', async () => {
+  const c = stubClient({ 500: src(500, 7, 3) });
+  const r = await withDescentPort([{ id: 500, depth: 1, relation: 'split' }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(r.credited, Math.round(BASE * QUICK * 0.5), '5 × 0.6 × 0.5 = 2 (rounded once)');
+  assert.equal(r.payments[0].depth, 1);
+  assert.equal(c.credited[0].builder_id, 3);
+});
+
+await test('each further hop halves again, and the rate is the DIAL not a constant', async () => {
+  const anc = [{ id: 500, depth: 1 }, { id: 501, depth: 2 }, { id: 502, depth: 3 }];
+  // FULL-grade origins at 100%, so all three hops still round to a credit and
+  // the halving is visible as a sequence rather than truncated by the floor.
+  const full = { grade: 'full', completeness: 100 };
+  const lineage = {
+    500: src(500, 7, 3, full), 501: src(501, 8, 4, full), 502: src(502, 9, 5, full),
+  };
+
+  const half = stubClient(lineage);
+  const rHalf = await withDescentPort(anc,
+    () => credits.awardIdeaDescentShipCredit(half, { taskId: 900, config: ON }));
+  assert.deepEqual(rHalf.payments.map((p) => p.delta), [
+    Math.round(BASE * 0.5), Math.round(BASE * 0.25), Math.round(BASE * 0.125),
+  ], 'each hop is the one above it, halved');
+
+  // A project that wants a shallower descent to matter less says so, and the
+  // arithmetic follows the setting rather than a hard-coded half.
+  const steep = stubClient(lineage);
+  const rSteep = await withDescentPort(anc,
+    () => credits.awardIdeaDescentShipCredit(steep, { taskId: 900, config: rewardPolicy({ ideaDescentDecay: 0.1 }) }));
+  assert.ok(rSteep.credited < rHalf.credited, 'a steeper decay pays a descent less');
+});
+
+await test('a descendant stops paying when its share no longer ROUNDS to a credit', async () => {
+  // The floor the spec left open (Q1) is arithmetic, not a hop limit: at the
+  // default rate a quick idea's share is under half a credit by depth 4.
+  const deep = [];
+  const lineage = {};
+  for (let d = 1; d <= 8; d += 1) {
+    deep.push({ id: 600 + d, depth: d });
+    lineage[600 + d] = src(600 + d, 100 + d, 3);
+  }
+  const c = stubClient(lineage);
+  const r = await withDescentPort(deep,
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.ok(r.payments.length > 0 && r.payments.length < 8,
+    `the deep tail pays nothing and is not booked — paid ${r.payments.length} of 8`);
+  assert.ok(r.payments.every((p) => p.delta > 0), 'no zero-credit row is ever written');
+  const maxDepth = Math.max(...r.payments.map((p) => p.depth));
+  assert.ok(deep.some((a) => a.depth > maxDepth), 'and there were deeper ancestors it declined to pay');
+});
+
+await test('a descent of ANY depth pays, in total, no more than the direct task did', async () => {
+  // The property that makes a hop limit unnecessary (spec decision 6). Sum of
+  // (1/2)^d over every hop is 1, so even an unbounded chain of DISTINCT origins
+  // cannot, between them, take more out of one ship than the ship's own direct
+  // payout. Sixty-four hops, every one a different idea — the worst case.
+  const anc = [];
+  const lineage = {};
+  for (let d = 1; d <= 64; d += 1) {
+    anc.push({ id: 700 + d, depth: d });
+    lineage[700 + d] = src(700 + d, 200 + d, 3);
+  }
+  const c = stubClient(lineage);
+  const r = await withDescentPort(anc,
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  const direct = Math.round(BASE * QUICK);
+  assert.ok(r.credited <= direct,
+    `the whole 64-hop descent paid ${r.credited}, which must not exceed the direct share ${direct}`);
+  assert.ok(r.payments.length < 5, 'and the deep tail is not even booked');
+});
+
+await test('the grade factor is the SAME one the direct payout applies', async () => {
+  // A full idea at 80% one hop down: 5 × 0.80 × 0.5. If the two paths kept
+  // separate copies of the clamp they could disagree, and the same idea would
+  // be worth different amounts depending on which hop shipped.
+  const c = stubClient({ 500: src(500, 7, 3, { grade: 'full', completeness: 80 }) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(r.credited, Math.round(BASE * 0.8 * 0.5), '5 × 0.80 × 0.5 = 2');
+});
+
+await test('a SPARK someone else developed splits the decayed share 70/30, like the direct one', async () => {
+  // R147 / ADR 0185: when someone other than the author developed the idea, both
+  // ideator streams split with them. The descent payout wires splitIdeaCredit up
+  // the same way, so the split has to be DRIVEN here — a fixture that always
+  // carries developed_by: null never enters that branch, and the branch that is
+  // never entered is the one that silently pays the wrong person.
+  const c = stubClient({ 500: src(500, 7, 3, { grade: 'full', completeness: 100, developed_by: 9 }) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  const delta = Math.round(BASE * 1 * 0.5);
+  assert.equal(r.credited, delta, 'the TOTAL is the decayed share — the split divides it, never inflates it');
+  assert.equal(c.credited.length, 2, 'two ledger rows, one per payee');
+  const byBuilder = Object.fromEntries(c.credited.map((x) => [String(x.builder_id), x.delta]));
+  assert.ok(byBuilder['9'] >= byBuilder['3'], 'the developer takes the larger 70% share');
+  assert.equal(byBuilder['9'] + byBuilder['3'], delta, 'and the two shares conserve the total');
+  assert.equal(new Set(c.credited.map((x) => x.reason)).size, 1,
+    'both rows share ONE reason — which is why the dedup must be builder-scoped');
+});
+
+await test('a SELF-developed idea collapses to one payee at the decayed rate', async () => {
+  // splitIdeaCredit collapses this deliberately: two rows for one builder would
+  // UNDER-pay under the per-builder idempotency predicate, not double-pay.
+  const c = stubClient({ 500: src(500, 7, 3, { grade: 'full', completeness: 100, developed_by: 3 }) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(c.credited.length, 1, 'one payee, one row');
+  assert.equal(r.credited, Math.round(BASE * 1 * 0.5), 'paid the whole decayed share');
+});
+
+// ---------------------------------------------------------------------------
+// 2. paid ONCE — the DAG cases
+// ---------------------------------------------------------------------------
+
+await test('one origin above a ship by TWO routes is paid ONCE, at the shorter', async () => {
+  // Ancestors 500 (depth 1) and 501 (depth 3) both trace to idea 7 — the shape a
+  // merge produces. Paying both would pay one origin twice for one ship.
+  const c = stubClient({ 500: src(500, 7, 3), 501: src(501, 7, 3) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }, { id: 501, depth: 3 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(r.payments.length, 1, 'one payment, not two');
+  assert.equal(r.payments[0].depth, 1, 'at the SHORTEST depth of the two');
+  assert.equal(c.credited.length, 1, 'and one ledger row');
+});
+
+await test('the DIRECT payout wins over a decayed one for the same idea', async () => {
+  // Idea 7 is both this task's own source AND an ancestor's source. It must be
+  // paid the full direct share, not the full share plus a decayed one.
+  const c = stubClient({ 500: src(500, 7, 3) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, skipIdeaIds: [7], config: ON }));
+  assert.equal(r.credited, 0);
+  assert.equal(r.payments.length, 0, 'the already-settled origin is skipped, not re-booked');
+  assert.equal(c.credited.length, 0);
+});
+
+await test('re-running the same ship never pays an origin twice', async () => {
+  const lineage = { 500: src(500, 7, 3), 501: src(501, 8, 4) };
+  const c = stubClient(lineage);
+  const anc = [{ id: 500, depth: 1 }, { id: 501, depth: 1 }];
+  const first = await withDescentPort(anc, () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.ok(first.credited > 0);
+  const rows = c.credited.length;
+  const again = await withDescentPort(anc, () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(again.credited, 0, 'the second run books nothing');
+  assert.equal(again.reason, 'already_paid');
+  assert.equal(c.credited.length, rows, 'and writes no further ledger rows');
+});
+
+await test('the reason key is per (idea, task) — the SAME key the direct payout uses', async () => {
+  // Not per (idea, task, depth): if the depth rode in the key, re-walking a
+  // descent that had changed shape would pay the same origin again for one ship.
+  const c = stubClient({ 500: src(500, 7, 3) });
+  await withDescentPort([{ id: 500, depth: 2 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(c.credited[0].reason, 'idea.credit.task_ship:7:900');
+  assert.doesNotMatch(c.credited[0].reason, /:2$|depth/, 'no depth in the key');
+});
+
+// ---------------------------------------------------------------------------
+// 3. the farming boundary — spec decision 7
+// ---------------------------------------------------------------------------
+
+await test('the payout reads no idea-to-idea relation — a citation cannot farm an origin', async () => {
+  // The descent SURFACE follows a merge (modules/ideas/trail-descent.js) so a
+  // merged thought still sees the work it caused. The PAYOUT must not, or filing
+  // a thought that cites an old one would mint credit from someone else's work.
+  const c = stubClient({ 500: src(500, 7, 3) });
+  await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  for (const q of c.log) {
+    assert.doesNotMatch(q.sql, /merged_into_idea_id/,
+      'a merge is an idea-to-idea relation and must not reach the money');
+  }
+  const SRC = fs.readFileSync(path.join(ROOT, 'modules/economy/credits.js'), 'utf8');
+  const fn = SRC.slice(SRC.indexOf('async function awardIdeaDescentShipCredit'));
+  const body = fn.slice(0, fn.indexOf('\n}\n'));
+  assert.doesNotMatch(body, /merged_into_idea_id|attachDescentToTrail|trail-descent/,
+    'nor may the function reach for the surface read that does follow merges');
+});
+
+await test('it walks the TASK edge table, not the idea lineage, to find its ancestors', async () => {
+  // The ancestors come from the port (ideas_task_descent, task→task); the
+  // lineage read only NAMES the idea behind each ancestor task. Reversing those
+  // two is how a citation graph would sneak in.
+  const SRC = fs.readFileSync(path.join(ROOT, 'modules/economy/credits.js'), 'utf8');
+  const fn = SRC.slice(SRC.indexOf('async function awardIdeaDescentShipCredit'));
+  const body = fn.slice(0, fn.indexOf('\n}\n'));
+  assert.match(body, /ancestorsOfTask/, 'the descent comes from the walk');
+  assert.match(body, /FROM ideas_task_lineage/, 'and the lineage read only resolves the origin');
+});
+
+// ---------------------------------------------------------------------------
+// 4. existing behaviour preserved
+// ---------------------------------------------------------------------------
+
+await test('a task with NO ancestors pays nothing and issues no lineage read', async () => {
+  const c = stubClient({});
+  const r = await withDescentPort([], () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON }));
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'no_ancestors');
+  assert.equal(c.log.length, 0);
+});
+
+await test('the ideator lane being OFF suppresses the descent payout too', async () => {
+  const c = stubClient({ 500: src(500, 7, 3) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: { ideatorCredit: false } }));
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'ideator_lane_off');
+  assert.equal(c.log.length, 0, 'the lane gate is checked before the walk, not after it');
+});
+
+await test('a decay of 0 restores exactly the old first-hop-only behaviour', async () => {
+  const c = stubClient({ 500: src(500, 7, 3) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: rewardPolicy({ ideaDescentDecay: 0 }) }));
+  assert.equal(r.credited, 0);
+  assert.equal(r.reason, 'decay_off');
+  assert.equal(c.log.length, 0, 'and it costs nothing — no walk, no read');
+});
+
+// ---------------------------------------------------------------------------
+// 5. the dial, and the wiring
+// ---------------------------------------------------------------------------
+
+await test('the PORT METHOD re-applies the convergence bound, not just the resolver', async () => {
+  // awardIdeaDescentShipCredit is reachable through the reward port with a
+  // caller-supplied config that never passed through rewardPolicy(). A rate of
+  // 1.5 would make a deeper ancestor pay MORE than a nearer one — the exact
+  // property the comments promise cannot happen.
+  const c = stubClient({ 500: src(500, 7, 3), 501: src(501, 8, 4) });
+  const r = await withDescentPort([{ id: 500, depth: 1 }, { id: 501, depth: 2 }],
+    () => credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: { ideatorCredit: true, ideaDescentDecay: 1.5 } }));
+  const deltas = r.payments.map((p) => p.delta);
+  for (let i = 1; i < deltas.length; i += 1) {
+    assert.ok(deltas[i] <= deltas[i - 1], `a deeper hop may never pay more — got ${JSON.stringify(deltas)}`);
+  }
+  assert.ok(r.credited <= Math.round(BASE * QUICK), 'and the total stays bounded by the direct share');
+});
+
+await test('the walk is capped at the depth the money can actually reach', async () => {
+  // Past the depth where even a 100%-complete idea rounds to nothing, every
+  // further hop is a round trip that provably pays nobody. The cap is derived
+  // from the rate, so a steeper decay walks LESS, never more.
+  let askedFor = null;
+  const c = stubClient({ 500: src(500, 7, 3) });
+  ancestorsFixture = [{ id: 500, depth: 1 }];
+  const port = api.resolve('ideas.descent');
+  const realWalk = port.ancestorsOfTask;
+  port.ancestorsOfTask = async (id, opts) => { askedFor = opts && opts.maxDepth; return realWalk(id, opts); };
+  try {
+    await credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: ON });
+    const atHalf = askedFor;
+    assert.ok(Number.isInteger(atHalf) && atHalf > 0 && atHalf < 64,
+      `the walk gets a derived cap, not the 64 backstop — got ${atHalf}`);
+    await credits.awardIdeaDescentShipCredit(c, { taskId: 901, config: rewardPolicy({ ideaDescentDecay: 0.1 }) });
+    assert.ok(askedFor < atHalf, `a steeper decay walks shallower — ${askedFor} vs ${atHalf}`);
+  } finally {
+    port.ancestorsOfTask = realWalk;
+    ancestorsFixture = [];
+  }
+});
+
+await test('the decay dial defaults to halving and refuses a non-converging rate', async () => {
+  assert.equal(rewardPolicy({}).ideaDescentDecay, IDEA_DESCENT_DECAY);
+  assert.equal(IDEA_DESCENT_DECAY, 0.5, 'spec decision 16: halving each hop');
+  assert.equal(rewardPolicy({ ideaDescentDecay: 0.25 }).ideaDescentDecay, 0.25, 'a project may set its own');
+  assert.equal(rewardPolicy({ ideaDescentDecay: 0 }).ideaDescentDecay, 0, '0 is legal — only the direct task pays');
+  for (const bad of [1, 1.5, -0.5, 'half', null, undefined, NaN]) {
+    assert.equal(rewardPolicy({ ideaDescentDecay: bad }).ideaDescentDecay, IDEA_DESCENT_DECAY,
+      `a rate of ${String(bad)} must fall back to the default, not poison an award`);
+  }
+});
+
+await test('the ship hook CALLS it, and hands it what the direct payout already settled', async () => {
+  // A payout nothing calls is dead code. The skipIdeaIds hand-off is what stops
+  // a direct source that is also an ancestor's source being paid twice, so the
+  // call site is pinned, not just the function.
+  const SHIP = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/db-ship.js'), 'utf8');
+  // ANCHORED ON THE CALL, not on the name. /reward\.awardIdeaDescentShipCredit/
+  // on its own still matches `reward.awardIdeaDescentShipCreditXX` — a typo'd
+  // call that resolves to undefined, takes the guard's else branch and skips
+  // the payout forever. Reverting the wiring has to red this, and with the bare
+  // name it did not. The open paren is what makes it assert a CALL.
+  assert.match(SHIP, /await reward\.awardIdeaDescentShipCredit\(/,
+    'the ship hook CALLS it through the reward port');
+  assert.match(SHIP, /skipIdeaIds:[\s\S]{0,120}ideaBonus[\s\S]{0,40}ideaId/,
+    'and passes the idea the direct payout just settled');
+  const PORT = fs.readFileSync(path.join(ROOT, 'modules/economy/reward.js'), 'utf8');
+  assert.match(PORT, /awardIdeaDescentShipCredit: \(\.\.\.a\) => credits\.awardIdeaDescentShipCredit\(/,
+    'the reward port publishes it, or the ship hook guard silently skips forever');
+});
+
+await test('ideas PROVIDES the port, and economy deliberately does NOT declare it as consumed', async () => {
+  // THE DECLARATION THAT WOULD BREAK BOOT, and the reason this is a test rather
+  // than a comment. `consumes` means REQUIRED: src/module-loader/loader.js
+  // verifyEnabledPorts THROWS and refuses to boot when an enabled module
+  // consumes a port no enabled module provides. The ideas module can be
+  // disabled; economy is default-on. So declaring ideas.descent in economy's
+  // consumes would turn "this instance does not use ideas" into "this instance
+  // does not start" — for a capability that is optional by construction and
+  // degrades to exactly today's first-hop payout.
+  //
+  // The next reader will see an undeclared port and want to tidy it up. This is
+  // the test that tells them why not.
+  const ideas = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/ideas/module.json'), 'utf8'));
+  const economy = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/economy/module.json'), 'utf8'));
+  assert.ok(ideas.provides.includes('ideas.descent'), 'ideas provides it');
+  assert.ok(!(economy.consumes || []).includes('ideas.descent'),
+    'economy must NOT require it — an instance with the ideas module off still has to boot');
+
+  const SRC = fs.readFileSync(path.join(ROOT, 'modules/economy/credits.js'), 'utf8');
+  assert.match(SRC, /resolveOptional\('ideas\.descent'\)/,
+    'which is only safe because it is resolved OPTIONALLY, never through resolve()');
+  assert.doesNotMatch(SRC, /[^t]resolve\('ideas\.descent'\)/,
+    'a hard resolve would throw on the request path instead of degrading');
+
+  const ROUTES = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/inbox.js'), 'utf8');
+  assert.match(ROUTES, /registerProvider\('ideas\.descent'/, 'and something actually registers it');
+  assert.match(ROUTES, /hasProvider\('ideas\.descent'\)/,
+    'guarded, or rebuilding the router trips the single-provider guard');
+});
+
+await test('the port publishes only names the walk actually exports', async () => {
+  // A guessed method name resolves to undefined and the payout silently pays
+  // nobody — the exact failure a port cannot surface at boot.
+  const descent = require('../modules/ideas/descent.js');
+  const ROUTES = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/inbox.js'), 'utf8');
+  const block = ROUTES.slice(ROUTES.indexOf("registerProvider('ideas.descent'"));
+  for (const name of [...block.slice(0, block.indexOf('}')).matchAll(/(\w+):\s*descent\.(\w+)/g)]) {
+    assert.equal(typeof descent[name[2]], 'function',
+      `descent.js must export ${name[2]} — the port publishes it`);
+  }
+  assert.equal(typeof descent.ancestorsOfTask, 'function', 'and the payout calls ancestorsOfTask by that name');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/idea_task_descent.mjs

@@ -66,7 +66,14 @@ function graphClient(edges) {
       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)))
-        .map((e) => ({ id: up ? e.parent_task_id : e.task_id, relation: e.relation }));
+        // 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 };
     },
   };
@@ -282,7 +289,7 @@ await test('syncDescentForTask REPORTS a refusal instead of throwing', async ()
         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, relation: 'split' }] };
+      if (/parent_task_id = ANY/.test(text)) return { rows: [{ id: 9, from_id: 5, relation: 'split' }] };
       return { rows: [] };
     },
   };