@bongos/core 1.19.900 → 1.19.902

package/modules/economy/reward-policy.js

@@ -28,6 +28,28 @@ const REWARD_MARGIN_PCT = 20;
 const REWARD_MODE_DEFAULT = 'cost-plus-and-estimate';
 const REWARD_MODE_COST_PLUS_ONLY = 'cost-plus-only';
 
+// The DEPTH DECAY on the ideator descent payout (task 1004088, BV2.R09; spec
+// decision 16). A task shipping pays the idea it came from in full; a task
+// shipping one hop BELOW that pays it this fraction, and so on down.
+//
+// WHY 0.5, AND WHY THE SERIES NEEDS NO CAP. At a half per hop an infinite
+// descent is worth at most twice the direct task, so the payout converges on
+// its own and nothing has to pick an arbitrary hop limit. A rate of 1 would not
+// converge — a wide enough descent could pay an origin without bound — so the
+// resolver refuses anything at or above 1 and falls back to the default.
+//
+// WHY IT LIVES HERE. The owner's ruling (interview Q1) is that the rate belongs
+// to the project, not to the platform, so it is a per-instance dial and this is
+// where per-instance reward policy already resolves. It is the SECOND such dial
+// (the ignite floor in modules/ideas/routing.js is the first), and BV2.R05 is
+// the task that gives the two of them one home; putting it in the existing
+// resolver now makes that a move rather than a rewrite.
+//
+// 0 IS A LEGAL SETTING and means "only the direct task pays" — an instance that
+// wants the old first-hop-only behaviour sets it and gets exactly that, with no
+// code path to disable separately.
+const IDEA_DESCENT_DECAY = 0.5;
+
 // PURE. Resolves a raw branding `reward` block over the code defaults. Every field
 // is validated rather than trusted: a malformed pack degrades to the defaults
 // instead of poisoning an award.
@@ -39,12 +61,23 @@ function rewardPolicy(rawReward) {
   const perTaskCredit = mode !== REWARD_MODE_COST_PLUS_ONLY;
   // Default-on, opt-out-only: only an explicit `false` withholds the ideator lane.
   const ideatorCredit = r.ideatorCredit !== false;
-  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit };
+  // Validated to [0, 1): see IDEA_DESCENT_DECAY above — a rate of 1 or more does
+  // not converge, and a negative one would pay a descent backwards.
+  // ABSENT IS THE DEFAULT, NOT ZERO — and Number(null) is 0, which is a legal
+  // rate meaning "only the direct task pays". Without this guard a pack that
+  // simply omits the key, or carries an explicit null, would silently switch
+  // the whole descent payout off and look exactly like a deliberate choice.
+  const rawDecay = r.ideaDescentDecay == null ? NaN : Number(r.ideaDescentDecay);
+  const ideaDescentDecay = Number.isFinite(rawDecay) && rawDecay >= 0 && rawDecay < 1
+    ? rawDecay
+    : IDEA_DESCENT_DECAY;
+  return { marginPct, usdPeg, mode, perTaskCredit, ideatorCredit, ideaDescentDecay };
 }
 
 module.exports = {
   REWARD_MARGIN_PCT,
   REWARD_MODE_DEFAULT,
   REWARD_MODE_COST_PLUS_ONLY,
+  IDEA_DESCENT_DECAY,
   rewardPolicy,
 };

package/modules/economy/reward.js

@@ -28,6 +28,10 @@ module.exports = {
   awardIdeaFullPassCredit: (...a) => credits.awardIdeaFullPassCredit(...a),
   // ADR 0172 IC4 — stream 1: pay the idea's author per shipped task, grade-scaled (replaces the 25% slice at ship).
   awardIdeaTaskShipCredit: (...a) => credits.awardIdeaTaskShipCredit(...a),
+  // BV2.R09 / ADR 0312 — the same stream, for the origins the shipping task
+  // DESCENDS from rather than the one it was promoted from, decayed by depth.
+  // Called right after the direct payout, which always wins for the same idea.
+  awardIdeaDescentShipCredit: (...a) => credits.awardIdeaDescentShipCredit(...a),
   // ADR 0172 IC5 — stream 3: a board-ratified Full Idea pays up to 100, scaled by completeness.
   // The board's close transaction resolves this port and calls this with its own
   // `client` (docs/specs/board-room-pass-event-contract.md) — the port is how

package/modules/hall-ui/public/profile.js

@@ -378,9 +378,55 @@
   const ideaHref = (id) => href(`${hallBase()}/idea/${encodeURIComponent(id)}`);
   const goalHref = (id) => href(`${hallBase()}/goals#/goal/${encodeURIComponent(id)}`);
 
+  // THE DESCENT — everything an idea's tasks went on to cause, at any depth and
+  // across version boundaries (task 1004089, BV2.R09; ADR 0312). Served as
+  // `descent_tasks`, already ordered nearest-first by the server, each entry at
+  // its shortest depth from one of the idea's own tasks.
+  //
+  // WHY IT RENDERS HERE, under the outcome and not beside it. The outcome line
+  // answers "what became of my idea" with the FIRST thing it became, which is
+  // all the trail could ever say while the read was one hop. The descent is the
+  // rest of that sentence, so it belongs in the same cell, subordinate to it.
+  //
+  // CAPPED, and the cap says so. The whole descent is the idea page's job
+  // (BV2.R10); a ledger row that paints forty tasks stops being a row. The
+  // overflow is a LINK to that page, never a silent truncation.
+  const DESCENT_SHOWN = 6;
+  function descentHtml(idea) {
+    const rows = Array.isArray(idea.descent_tasks) ? idea.descent_tasks : [];
+    if (!rows.length) return '';
+    const cells = rows.slice(0, DESCENT_SHOWN).map((t) => {
+      // The version is printed rather than compared away. A descendant living
+      // in a LATER version is the interesting case — it is the proof that an
+      // origin tag survives a version boundary — so it is labelled, not
+      // filtered and not silently flattened into the idea's own version.
+      const meta = [
+        `${escapeHtml(String(t.relation || 'descends'))}`,
+        `depth ${escapeHtml(String(t.depth))}`,
+        t.version_id ? escapeHtml(String(t.version_id)) : null,
+      ].filter(Boolean).join(' · ');
+      return `<span style="display:block;margin-top:2px">`
+        + `<a href="${taskHref(t.task_id)}">#${escapeHtml(String(t.task_id))} ${escapeHtml(t.title || '')}</a>`
+        + ` <span style="font-size:11px;color:var(--ink-faint)">${meta}</span>`
+        + `</span>`;
+    }).join('');
+    const rest = rows.length - DESCENT_SHOWN;
+    const more = rest > 0
+      ? `<span style="display:block;margin-top:2px;font-size:12px"><a href="${ideaHref(idea.id)}">and ${escapeHtml(String(rest))} more below this thought</a></span>`
+      : '';
+    return `<span style="display:block;margin-top:4px;font-size:12px;color:var(--ink-faint)">`
+      + `Then caused ${escapeHtml(String(rows.length))} ${rows.length === 1 ? 'task' : 'tasks'}</span>`
+      + cells + more;
+  }
+
   // What became of one idea, in a sentence a person can read. The four outcomes
   // the criterion names, each linked through to the thing it became.
   function ideaOutcomeHtml(idea) {
+    // The descent rides under EVERY outcome, not just a promotion: a merged
+    // idea inherits the descent of the idea it merged into (that is what
+    // "nothing is lost" means), and an idea whose first task was later split
+    // has a descent whatever its own status says.
+    const descent = descentHtml(idea);
     const note = idea.triage_note
       ? `<span style="display:block;margin-top:2px;font-size:12px;color:var(--ink-faint)">${escapeHtml(idea.triage_note)}</span>`
       : '';
@@ -396,19 +442,19 @@
           : []);
       // 'promoted' with nothing to point at is a real (old) state, not a bug to
       // paper over — say what is known rather than inventing a link.
-      if (!links.length) return `<span class="task__tag">Promoted</span>${note}`;
-      return `<span class="task__tag">Became ${links.length === 1 ? 'a task' : `${links.length} tasks`}</span> ${links.join(' · ')}${note}`;
+      if (!links.length) return `<span class="task__tag">Promoted</span>${note}${descent}`;
+      return `<span class="task__tag">Became ${links.length === 1 ? 'a task' : `${links.length} tasks`}</span> ${links.join(' · ')}${note}${descent}`;
     }
     if (idea.status === 'merged') {
       const target = idea.merged_into_idea_id
         ? ` <a href="${ideaHref(idea.merged_into_idea_id)}">#${escapeHtml(String(idea.merged_into_idea_id))} ${escapeHtml(idea.merged_into_idea_title || '')}</a>`
         : '';
-      return `<span class="task__tag">Merged into</span>${target}${note}`;
+      return `<span class="task__tag">Merged into</span>${target}${note}${descent}`;
     }
     if (idea.status === 'discarded') {
-      return `<span class="task__tag">Discarded</span>${note}`;
+      return `<span class="task__tag">Discarded</span>${note}${descent}`;
     }
-    return `<span class="task__tag">Still open</span>${note}`;
+    return `<span class="task__tag">Still open</span>${note}${descent}`;
   }
 
   // One ledger driven by one server-paged endpoint. `fetchPage(offset, perPage)`

package/modules/ideas/descent.js

@@ -22,8 +22,94 @@ const DESCENT_MAX_DEPTH = 64;
 
 const DESCENT_RELATIONS = Object.freeze(['rewrite', 'split', 'merge', 'fold', 'cascade']);
 
-// walk — breadth-first over the edge table, one query PER LEVEL.
+// ── the walk: one implementation, batched and single-root ─────────────────
+// walkMany — a breadth-first walk from MANY roots at once: ONE query per LEVEL
+// for the whole set, rather than one walk per root.
 //
+// WHY THE BATCH IS THE POINT OF THIS FUNCTION (task 1004089, BV2.R09). The
+// descent is read for a PAGE of ideas, not for one. Walking each root on its
+// own costs (roots x depth) round trips, which is the 4-6 serial round trips
+// per read that sank the previous attempt at this read. Batched, the cost is
+// depth round trips for the whole page — INDEPENDENT of how many ideas the page
+// carries, which is the property tests/idea_trail_descent.mjs pins.
+//
+// WHY NOT A RECURSIVE CTE, which collapses it to literally one query: the walk
+// comment above says it, and nothing about batching changes that argument. A
+// CTE re-expands every path, so a convergent DAG costs work exponential in
+// depth; here the whole page costs at most one query per level whatever the
+// shape. One query per level is the floor a walk that must not blow up can
+// reach, and this is that floor.
+//
+// PER-ROOT ATTRIBUTION is why the row carries `from_id`. The union of every
+// root's frontier goes to the database in one array, so a row coming back has
+// to say which frontier node produced it or the answer cannot be split back
+// apart. Depth is per-root and must stay that way: the payout decays by the
+// depth from THAT origin, so one shared answer would pay the wrong rate.
+//
+// Returns Map<rootKey, rows> — rootKey is String(rootId), rows exactly as the
+// single-root walk returns them.
+async function walkMany(startIds, direction, { maxDepth = DESCENT_MAX_DEPTH, client = null } = {}) {
+  const q = client || pool;
+  // Two literal statements rather than one with an interpolated column name:
+  // nothing here is caller-controlled, and a query built by concatenation is a
+  // shape a reader (and a scanner) has to stop and prove safe.
+  const SQL_UP = `SELECT parent_task_id AS id, task_id AS from_id, relation
+                    FROM ideas_task_descent
+                   WHERE task_id = ANY($1::bigint[])`;
+  const SQL_DOWN = `SELECT task_id AS id, parent_task_id AS from_id, relation
+                      FROM ideas_task_descent
+                     WHERE parent_task_id = ANY($1::bigint[])`;
+  const sql = direction === 'up' ? SQL_UP : SQL_DOWN;
+
+  // A root that is not a positive integer is dropped here rather than sent to
+  // the database as part of a bigint[]. linkTaskDescent already rejects a bad
+  // id by name before it ever walks; this is the second line, for the readers
+  // that take their roots from a row rather than from an argument.
+  const roots = [...new Set((startIds || []).map((r) => String(r)))].filter((r) => /^[1-9]\d*$/.test(r));
+
+  // One independent walk state per root, stepped in lockstep so that every
+  // root's frontier is expanded by the same query.
+  const state = new Map();
+  for (const r of roots) {
+    state.set(r, { found: new Map(), visited: new Set([r]), frontier: [Number(r)] });
+  }
+
+  for (let depth = 1; depth <= maxDepth; depth += 1) {
+    const union = new Set();
+    for (const s of state.values()) for (const n of s.frontier) union.add(n);
+    if (union.size === 0) break;
+    const { rows } = await q.query(sql, [[...union]]);
+    // from_id -> the edges it produced, so each root can expand only the nodes
+    // that were actually on ITS frontier.
+    const adjacency = new Map();
+    for (const row of rows) {
+      const from = String(row.from_id);
+      if (!adjacency.has(from)) adjacency.set(from, []);
+      adjacency.get(from).push(row);
+    }
+    for (const s of state.values()) {
+      const next = [];
+      for (const node of s.frontier) {
+        for (const edge of adjacency.get(String(node)) || []) {
+          const key = String(edge.id);
+          if (s.visited.has(key)) continue;   // already reached at a shallower depth
+          s.visited.add(key);
+          s.found.set(key, { id: edge.id, depth, relation: edge.relation });
+          next.push(Number(edge.id));
+        }
+      }
+      s.frontier = next;
+    }
+  }
+
+  const out = new Map();
+  for (const [root, s] of state) {
+    out.set(root, [...s.found.values()].sort((a, b) => a.depth - b.depth || Number(a.id) - Number(b.id)));
+  }
+  return out;
+}
+
+// Both of the above are breadth-first over the edge table, one query PER LEVEL.
 // WHY NOT A RECURSIVE CTE, which is the obvious shape and was the first cut.
 // A recursive CTE's working table re-expands every path independently, so a
 // densely-connected DAG — paths that converge and diverge again, which is
@@ -43,37 +129,13 @@ const DESCENT_RELATIONS = Object.freeze(['rewrite', 'split', 'merge', 'fold', 'c
 // The cost is one round trip per level instead of one per walk. Depth decay
 // halves each hop (spec decision 16), so a descent deep enough for that to
 // matter is already worth almost nothing.
-async function walk(startId, direction, { maxDepth = DESCENT_MAX_DEPTH, client = null } = {}) {
-  const q = client || pool;
-  // Two literal statements rather than one with an interpolated column name:
-  // nothing here is caller-controlled, and a query built by concatenation is a
-  // shape a reader (and a scanner) has to stop and prove safe.
-  const SQL_UP = `SELECT parent_task_id AS id, relation
-                    FROM ideas_task_descent
-                   WHERE task_id = ANY($1::bigint[])`;
-  const SQL_DOWN = `SELECT task_id AS id, relation
-                      FROM ideas_task_descent
-                     WHERE parent_task_id = ANY($1::bigint[])`;
-  const sql = direction === 'up' ? SQL_UP : SQL_DOWN;
-
-  const found = new Map();
-  const visited = new Set([String(startId)]);
-  let frontier = [Number(startId)];
-
-  for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth += 1) {
-    const { rows } = await q.query(sql, [frontier]);
-    const next = [];
-    for (const r of rows) {
-      const key = String(r.id);
-      if (visited.has(key)) continue;   // already reached at a shallower depth
-      visited.add(key);
-      found.set(key, { id: r.id, depth, relation: r.relation });
-      next.push(Number(r.id));
-    }
-    frontier = next;
-  }
-
-  return [...found.values()].sort((a, b) => a.depth - b.depth || Number(a.id) - Number(b.id));
+// walk — the single-root walk, which is walkMany with one root. ONE
+// implementation on purpose: the payout (R11) walks up and the descent surface
+// (R10) walks down, and a second copy of the de-duplication would be free to
+// drift from this one — a drift that shows up as money, not as a render bug.
+async function walk(startId, direction, opts = {}) {
+  const byRoot = await walkMany([startId], direction, opts);
+  return byRoot.get(String(startId)) || [];
 }
 
 // ancestorsOfTask — every task this one descends from, nearest first, each at
@@ -87,6 +149,14 @@ function descendantsOfTask(taskId, opts = {}) {
   return walk(taskId, 'down', opts);
 }
 
+// descendantsOfTasks — the descent below SEVERAL roots, in one batch. What the
+// trail read (modules/ideas/trail-descent.js) consumes: a page of ideas has a
+// root task per promotion, and the whole page must cost one query per level,
+// not one walk per idea. Returns Map<String(rootId), rows>.
+function descendantsOfTasks(taskIds, opts = {}) {
+  return walkMany(taskIds, 'down', opts);
+}
+
 // linkTaskDescent — record that `taskId` came out of `parentTaskId`.
 //
 // Idempotent on the pair, because the derivation below runs on every ship and
@@ -209,6 +279,7 @@ module.exports = {
   linkTaskDescent,
   ancestorsOfTask,
   descendantsOfTask,
+  descendantsOfTasks,
   deriveEdgesForTask,
   syncDescentForTask,
 };

package/modules/ideas/module.json

@@ -17,7 +17,8 @@
     ]
   },
   "provides": [
-    "ideas.capture"
+    "ideas.capture",
+    "ideas.descent"
   ],
   "consumes": [
     "reward",

package/modules/ideas/routes/inbox.js

@@ -35,6 +35,12 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const inbox = require('../inbox');
+// The trail read to the FULL depth of the descent (task 1004089, BV2.R09). Its
+// own file because inbox.js is AT the size ratchet and because a task->task
+// walk is a different relation from the idea->task trail.
+const { attachDescentToTrail } = require('../trail-descent');
+// The walk itself, published as the `ideas.descent` port below.
+const descent = require('../descent');
 // Full Idea capture (task 1002919 / BV1.R143): the template validator (R141)
 // and the deterministic scorer (R142) — both pure, both walk the declaration.
 const { validateFieldValues, templateFor, fieldOrder } = require('../templates');
@@ -57,10 +63,34 @@ const { TRIAGE_NOTE_MAX } = inbox;
 // hook that runs both in the live server AND when a test rebuilds the GDS
 // router) and hasProvider-guarded so re-instantiation never trips the seam's
 // single-provider guard. Mirrors modules/economy/routes/reward.js.
+// The `ideas.descent` kernel PORT (task 1004088, BV2.R09; ADR 0312 + ADR 0093
+// §5). The ideator payout follows the task→task descent and decays by depth, so
+// modules/economy/credits.js has to know how far a shipping task sits below the
+// task an idea was promoted into.
+//
+// WHY A PORT AND NOT A SECOND SQL READ, which is what credits.js does for the
+// lineage. A cross-table SQL read across the module wall is allowed and credits.js
+// already relies on that; a cross-module require is not. But the descent is not a
+// read, it is a WALK — breadth-first with a visited set, each node at its shortest
+// depth — and a second copy of that in economy would be free to drift from this
+// one. The payout decays by the depth the walk returns, so a drift between the two
+// copies is not a rendering difference, it is a different amount of money. One
+// implementation, reached through the switchboard.
+//
+// Registered here beside `ideas.capture` for the same reason: the route factory is
+// the one boot hook that runs both in the live server and when a test rebuilds the
+// GDS router. hasProvider-guarded so re-instantiation never trips the single-
+// provider guard.
 function registerSeams() {
   if (!api.hasProvider('ideas.capture')) {
     api.registerProvider('ideas.capture', inbox.captureIdea);
   }
+  if (!api.hasProvider('ideas.descent')) {
+    api.registerProvider('ideas.descent', {
+      ancestorsOfTask: descent.ancestorsOfTask,
+      descendantsOfTask: descent.descendantsOfTask,
+    });
+  }
 }
 
 // The author-facing shape of a ratification window this request just opened —
@@ -552,6 +582,12 @@ module.exports = function buildInboxRouter() {
       inbox.listIdeaTrailForBuilder(builderId, { limit, offset, viewerRank }),
       inbox.countIdeaTrailForBuilder(builderId, { viewerRank }),
     ]);
+    // Everything those tasks went on to cause, to any depth and across version
+    // boundaries (BV2.R09, ADR 0312). Composed here rather than inside the trail
+    // read: the descent is a task->task walk, the trail is an idea->task read,
+    // and the walk is batched across the WHOLE page — so it stays one query per
+    // level however many ideas the window carries, never one walk per idea.
+    await attachDescentToTrail(ideas);
     return res.json({ builder_id: builderId, ideas, total, limit, offset });
   }, { errorCode: 'idea_trail_failed' }));
 

package/modules/ideas/trail-descent.js

@@ -0,0 +1,224 @@
+// modules/ideas/trail-descent.js — the idea trail, read to the FULL depth of
+// the descent instead of one hop (task 1004089, BV2.R09, goal 1000095;
+// ADR 0312, spec docs/specs/bongos-v2-ideator-surface.md).
+//
+// WHAT WAS MISSING. listIdeaTrailForBuilder (modules/ideas/inbox.js) answers
+// "what became of the idea I filed" with `lineage_tasks[]` — the tasks the idea
+// was promoted INTO, and nothing further. That is one hop. Everything those
+// tasks then caused — the split that broke one of them in two, the cascade a
+// ship fired, the task that folded into another — is recorded in
+// ideas_task_descent and shown nowhere. An ideator reading their own trail sees
+// the first thing their thought caused and none of the rest of it, which is the
+// opposite of the promise the surface makes.
+//
+// WHY IT IS A SEPARATE FILE rather than more of listIdeaTrailForBuilder. Two
+// reasons, and the second is the real one. inbox.js is AT the 1500-line size
+// ratchet (scripts/gds/fitness-ratchets.js), so a line added there fails the
+// build — the same wall that put descent.js beside it. And the descent is a
+// different relation from the trail: the trail is idea → task (one query, one
+// page window), the descent is task → task (a walk). Composing them here keeps
+// the trail read a trail read, and keeps this walk usable by the payout and the
+// detail surface without dragging the page window along with it.
+//
+// THREE FINDINGS INHERITED FROM THE ABANDONED TASK 1004054 are design
+// requirements here, not history:
+//
+//   1. TEST AT THE RENDERED LAYER. The prior attempt tested the server-side
+//      trail builder only, which is exactly why finding 2 survived it. What a
+//      reader actually gets is HTML, so tests/idea_trail_descent.mjs runs the
+//      real modules/hall-ui/public/profile.js and asserts on that HTML.
+//   2. A MERGED IDEA CARRIES ITS OWN TRIAGE NOTE. When idea A is merged into
+//      idea B, the descent A should show is the one running through B's tasks —
+//      that is what "nothing is lost" means (ADR 0311). The note beside it is
+//      still A's own, off the MERGED row, because that note is the sentence the
+//      triager wrote about A. Reading the note from the target instead is the
+//      bug that broke the headline scenario last time, so the merge follow here
+//      deliberately carries task ids ONLY, never prose.
+//   3. NOT PER-HOP ROUND TRIPS. The prior attempt cost 4-6 serial round trips
+//      per read. This costs, for a WHOLE PAGE of ideas: one query to follow the
+//      merges, one query per level of the deepest descent on the page, and one
+//      to name the tasks found. The count tracks depth and is INDEPENDENT of
+//      how many ideas the page carries — pinned as an assertion, because that
+//      independence is the whole claim and it is invisible in review.
+//
+// ACROSS VERSIONS, deliberately and by omission: no read below filters on
+// version_id, and the hydration returns it so a surface can SAY that a
+// descendant lives in a later version. A thought does not stop being the origin
+// of the work it caused because the work crossed a version boundary; the
+// one-level cap and the cross-version refusal that ADR 0312 left alone belong
+// to ideas_task_lineage, which is a different table.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const { descendantsOfTasks, DESCENT_MAX_DEPTH } = require('./descent');
+
+// A positive integer id, as it arrives off a row — where it may be a bigint
+// serialised to a string. Anything else is dropped rather than sent to the
+// database inside a bigint[].
+function idOf(v) {
+  return /^[1-9]\d*$/.test(String(v)) ? String(v) : null;
+}
+
+// directRootsForIdea — the tasks an idea became, which are the roots its
+// descent hangs below. ideas_task_lineage is the complete answer (one idea can
+// become many tasks, task 1002997); promoted_to_task_id is the only answer for
+// promotions that predate that table, so it is the fallback, exactly as the
+// trail read and the profile renderer already treat it.
+function directRootsForIdea(idea) {
+  const out = [];
+  const lineage = Array.isArray(idea.lineage_tasks) ? idea.lineage_tasks : [];
+  for (const t of lineage) {
+    const id = idOf(t && t.task_id);
+    if (id) out.push(id);
+  }
+  if (out.length === 0) {
+    const legacy = idOf(idea.promoted_to_task_id);
+    if (legacy) out.push(legacy);
+  }
+  return out;
+}
+
+// followMerges — a merged idea inherits its TARGET's root tasks.
+//
+// One query for every merge on the page. The read is task ids and nothing else:
+// see finding 2 above — prose from the target row must not travel with them, or
+// the merged idea starts showing somebody else's triage note as its own.
+//
+// Only one hop is followed. A merge chain cannot exist: updateIdea in
+// modules/ideas/inbox.js throws MERGE_TARGET_MERGED when the target is itself
+// merged (the no-chains guard, core_195), so a second hop would be walking an
+// edge the writer will not write.
+async function followMerges(ideas, q) {
+  const targets = new Map();   // targetIdeaId -> [idea, ...] that merged into it
+  for (const idea of ideas) {
+    if (idea.status !== 'merged') continue;
+    const target = idOf(idea.merged_into_idea_id);
+    if (!target) continue;
+    if (!targets.has(target)) targets.set(target, []);
+    targets.get(target).push(idea);
+  }
+  if (targets.size === 0) return new Map();
+
+  const { rows } = await q.query(
+    `SELECT i.id AS idea_id, i.promoted_to_task_id, l.task_id
+       FROM idea_inbox i
+       LEFT JOIN ideas_task_lineage l ON l.idea_id = i.id
+      WHERE i.id = ANY($1::bigint[])`,
+    [[...targets.keys()]]
+  );
+
+  const byTarget = new Map();
+  for (const row of rows) {
+    const target = String(row.idea_id);
+    if (!byTarget.has(target)) byTarget.set(target, { lineage: [], legacy: idOf(row.promoted_to_task_id) });
+    const id = idOf(row.task_id);
+    if (id) byTarget.get(target).lineage.push(id);
+  }
+
+  const inherited = new Map();   // ideaId -> [rootTaskId, ...]
+  for (const [target, seen] of byTarget) {
+    const roots = seen.lineage.length > 0 ? seen.lineage : (seen.legacy ? [seen.legacy] : []);
+    for (const idea of targets.get(target) || []) {
+      inherited.set(String(idea.id), roots);
+    }
+  }
+  return inherited;
+}
+
+// hydrate — turn the ids the walk found into things a reader can read. One
+// query for every descendant on the page.
+//
+// version_id rides along BECAUSE the descent crosses versions: a descendant in
+// a later version is the interesting case, not an anomaly to hide, and a
+// surface cannot mark it without being told.
+async function hydrate(taskIds, q) {
+  const byId = new Map();
+  if (taskIds.length === 0) return byId;
+  const { rows } = await q.query(
+    `SELECT id, title, status, version_id, kind
+       FROM tasks
+      WHERE id = ANY($1::bigint[])`,
+    [taskIds.map(Number)]
+  );
+  for (const row of rows) byId.set(String(row.id), row);
+  return byId;
+}
+
+// attachDescentToTrail — the whole read, composed.
+//
+// Mutates nothing the caller did not ask for: every idea comes back with a
+// `descent_tasks` array, empty for an idea that caused nothing. Empty is an
+// ANSWER here, the same way 'still open' is an outcome on the trail — a filer
+// whose idea produced one task and no descent must see that, not a missing key
+// the renderer has to guess about.
+async function attachDescentToTrail(ideas, { client = null, maxDepth = DESCENT_MAX_DEPTH } = {}) {
+  const list = Array.isArray(ideas) ? ideas : [];
+  if (list.length === 0) return list;
+  const q = client || pool;
+
+  const inherited = await followMerges(list, q);
+
+  // rootsByIdea is what each idea's descent hangs below; rootUnion is what goes
+  // to the walk, deduplicated, so two ideas sharing a root cost one walk.
+  const rootsByIdea = new Map();
+  const rootUnion = new Set();
+  for (const idea of list) {
+    const roots = new Set(directRootsForIdea(idea));
+    for (const r of inherited.get(String(idea.id)) || []) roots.add(r);
+    rootsByIdea.set(String(idea.id), roots);
+    for (const r of roots) rootUnion.add(r);
+  }
+
+  const byRoot = rootUnion.size > 0
+    ? await descendantsOfTasks([...rootUnion], { client, maxDepth })
+    : new Map();
+
+  const found = new Set();
+  for (const rows of byRoot.values()) for (const r of rows) found.add(String(r.id));
+  const titles = await hydrate([...found], q);
+
+  for (const idea of list) {
+    const roots = rootsByIdea.get(String(idea.id)) || new Set();
+    // Shortest depth wins when a descendant is reachable from two of this
+    // idea's roots — the same rule the walk applies within one root, for the
+    // same reason: the payout decays by depth, so one descendant must resolve
+    // to one depth or the origin is paid twice for it (ADR 0312).
+    const best = new Map();
+    for (const root of roots) {
+      for (const row of byRoot.get(root) || []) {
+        const key = String(row.id);
+        // A root of THIS idea is already in lineage_tasks — the trail shows it
+        // as what the idea became, so repeating it below as its own descendant
+        // would double-count the first hop.
+        if (roots.has(key)) continue;
+        const prev = best.get(key);
+        if (prev && prev.depth <= row.depth) continue;
+        best.set(key, { depth: row.depth, relation: row.relation, origin_task_id: root });
+      }
+    }
+
+    idea.descent_tasks = [...best.entries()]
+      .map(([taskId, hit]) => {
+        const t = titles.get(taskId) || {};
+        return {
+          task_id: taskId,
+          depth: hit.depth,
+          relation: hit.relation,
+          origin_task_id: hit.origin_task_id,
+          title: t.title ?? null,
+          status: t.status ?? null,
+          version_id: t.version_id ?? null,
+          kind: t.kind ?? null,
+        };
+      })
+      .sort((a, b) => a.depth - b.depth || Number(a.task_id) - Number(b.task_id));
+  }
+
+  return list;
+}
+
+module.exports = {
+  attachDescentToTrail,
+  directRootsForIdea,
+  followMerges,
+};

package/modules/lifecycle/db-ship.js

@@ -371,11 +371,26 @@ async function awardLandingCredit(client, { taskId, creditedBuilderId, creditsRe
   const ideaBonus = reward.awardIdeaTaskShipCredit
     ? await reward.awardIdeaTaskShipCredit(client, { taskId })
     : null;
+  // BV2.R09 (ADR 0312): the same stream, for the origins this task DESCENDS
+  // from. The direct payout above pays the idea whose lineage row names this
+  // task; this pays the ideas above it in the task→task descent, decayed by
+  // depth. Its skipIdeaIds carries whatever the direct payout just settled, so
+  // an idea that is both the direct source AND an ancestor's source is paid the
+  // full share once rather than the full share plus a decayed one.
+  // Guarded the same way — an older economy module without this export, or an
+  // instance with no ideas module, simply pays nothing extra.
+  const ideaDescent = reward.awardIdeaDescentShipCredit
+    ? await reward.awardIdeaDescentShipCredit(client, {
+      taskId,
+      skipIdeaIds: ideaBonus && ideaBonus.ideaId != null ? [ideaBonus.ideaId] : [],
+    })
+    : null;
   return {
     creditsAwarded: credit.creditsAwarded,
     creditsRaw: credit.raw,
     creditsMultiplier: credit.multiplier,
     ideaBonus,
+    ideaDescent,
   };
 }
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.900",
+  "version": "1.19.902",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.900",
+      "version": "1.19.902",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.900",
+  "version": "1.19.902",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",