@bongos/core 1.19.899 → 1.19.901

package/modules/ideas/descent.js

@@ -0,0 +1,285 @@
+// modules/ideas/descent.js — task→task provenance edges: the relation that
+// makes an origin tag survive a rewrite, a split and a merge (task 1004086,
+// BV2.R07, goal 1000095; ADR 0312).
+//
+// WHY THIS IS ITS OWN FILE, beside inbox.js rather than inside it. ADR 0312's
+// central claim is that provenance is a DIFFERENT RELATION from both work
+// decomposition (tasks.parent_task_id) and idea→task lineage
+// (ideas_task_lineage): the first answers "what is this work part of", the
+// second "which thought opened this work", and this one "where did this work
+// come from". Keeping it in its own module is that argument in the file layout
+// — and it keeps inbox.js under the size ratchet, which adding it there broke.
+//
+// Reads the shared pool through the published doorway (src/module-api.js — the
+// only core file a module may require, ADR 0083), the same way inbox.js does.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+
+// The walk is bounded, but the bound is a backstop, not the safety property —
+// see walk() below, which cannot revisit a node and therefore cannot loop.
+const DESCENT_MAX_DEPTH = 64;
+
+const DESCENT_RELATIONS = Object.freeze(['rewrite', 'split', 'merge', 'fold', 'cascade']);
+
+// ── 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
+// exactly what a merge followed by a split produces — costs work exponential
+// in depth, and a final GROUP BY cannot undo that because the blow-up has
+// already happened inside the recursion. A depth bound caps the depth and does
+// nothing about the breadth.
+//
+// Level-by-level BFS with a visited set fixes both at once. A node is expanded
+// AT MOST ONCE ever, so the total work is bounded by the size of the reachable
+// subgraph rather than by the number of paths through it, and the FIRST time a
+// node is reached is necessarily its SHORTEST depth — which is the depth the
+// payout decays by, and the one that stops a single descendant paying the same
+// origin twice. It also makes cycle-safety structural rather than a bound to
+// remember: a cycle simply has nothing new to visit and the walk ends.
+//
+// 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.
+// 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
+// its shortest depth. This is what the payout (R09) walks.
+function ancestorsOfTask(taskId, opts = {}) {
+  return walk(taskId, 'up', opts);
+}
+
+// descendantsOfTask — the other direction, for the descent view (R10).
+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
+// may legitimately see the same signal twice.
+async function linkTaskDescent(taskId, parentTaskId, relation, { client = null } = {}) {
+  const child = Number(taskId);
+  const parent = Number(parentTaskId);
+  if (!Number.isInteger(child) || !Number.isInteger(parent) || child <= 0 || parent <= 0) {
+    throw { code: 'DESCENT_BAD_ID', task_id: taskId, parent_task_id: parentTaskId };
+  }
+  if (child === parent) {
+    throw { code: 'DESCENT_SELF_EDGE', task_id: child };
+  }
+  // Validated here as well as by the DB CHECK. The constraint is the guarantee;
+  // this is the error message — a rejected enum should name the caller's bad
+  // value, not surface as a constraint violation from three frames down.
+  if (!DESCENT_RELATIONS.includes(relation)) {
+    throw { code: 'DESCENT_BAD_RELATION', relation, allowed: DESCENT_RELATIONS };
+  }
+  // Would this close a loop? It does if the proposed PARENT already DESCENDS
+  // from the child. Unbounded on purpose: walk() cannot revisit a node, so it
+  // always terminates, and a bound here would silently miss a cycle whose
+  // closing edge sits deeper than the bound — which is the one case that
+  // matters, because that cycle is the one that gets written.
+  const reachable = await descendantsOfTask(child, { client, maxDepth: Infinity });
+  if (reachable.some((r) => Number(r.id) === parent)) {
+    throw { code: 'DESCENT_CYCLE', task_id: child, parent_task_id: parent };
+  }
+  const q = client || pool;
+  await q.query(
+    `INSERT INTO ideas_task_descent (task_id, parent_task_id, relation)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (task_id, parent_task_id) DO UPDATE
+        SET relation = EXCLUDED.relation`,
+    [child, parent, relation]
+  );
+}
+
+// ── the derivation: three signals the system already has ────────────────────
+//
+// ADR 0312's finding was that three seams already know a task was derived and
+// none of them is telling anyone. This turns each into an edge.
+//
+// WHY IT IS PULLED FROM `tasks` HERE rather than written by the code that
+// causes it. A module may not import another module (ADR 0083, rule 1), so
+// modules/lifecycle/cascade.js cannot call into this file, and `tasks` is the
+// protected lifecycle module's table so this may not add a column to it. What
+// IS available is a read of `tasks` (the ideas_002 precedent — a FK, and a
+// SELECT, are reads) and the `task.shipped` event on the published doorway.
+// So the ideas module derives its own edges from facts already on the row,
+// reacting to the event. Nothing in lifecycle changes.
+const CASCADE_SOURCE_REF = /-(\d+)$/;
+
+async function deriveEdgesForTask(taskId, { client = null } = {}) {
+  const q = client || pool;
+  const id = Number(taskId);
+  if (!Number.isInteger(id) || id <= 0) return [];
+
+  const { rows } = await q.query(
+    `SELECT t.id, t.source, t.source_ref, t.parent_task_id,
+            (SELECT array_agg(m.id)
+               FROM tasks m
+              WHERE m.merged_into_task_id = t.id) AS folded_in
+       FROM tasks t
+      WHERE t.id = $1`,
+    [id]
+  );
+  const t = rows[0];
+  if (!t) return [];
+
+  const edges = [];
+
+  // 1. CASCADE — cascade.js writes `cascade-<key>-<originating id>` into
+  //    source_ref. The key itself contains dashes ('artist-review-on-ship'),
+  //    so the id is the trailing numeric run, not the third segment.
+  if (t.source === 'cascade' && typeof t.source_ref === 'string') {
+    const m = CASCADE_SOURCE_REF.exec(t.source_ref);
+    if (m) edges.push({ parent: Number(m[1]), relation: 'cascade' });
+  }
+
+  // 2. SPLIT — the one-level work decomposition. The hierarchy keeps owning
+  //    what the work is PART OF; this records that it CAME FROM it.
+  if (t.parent_task_id != null) {
+    edges.push({ parent: Number(t.parent_task_id), relation: 'split' });
+  }
+
+  // 3. FOLD — tasks abandoned INTO this one (core_232 constrains
+  //    merged_into_task_id to abandoned rows). The mockup's "satellite": work
+  //    that stopped being its own thing and now orbits this one.
+  for (const foldedId of t.folded_in || []) {
+    edges.push({ parent: Number(foldedId), relation: 'fold' });
+  }
+
+  return edges.filter((e) => Number.isInteger(e.parent) && e.parent > 0 && e.parent !== id);
+}
+
+// syncDescentForTask — derive and record, tolerantly.
+//
+// Returns what it wrote and what it skipped rather than throwing: this runs off
+// a ship event, and a provenance edge must never be able to break a ship. A
+// refused cycle is a normal outcome here, not an error.
+async function syncDescentForTask(taskId, { client = null } = {}) {
+  const edges = await deriveEdgesForTask(taskId, { client });
+  const written = [];
+  const skipped = [];
+  for (const e of edges) {
+    try {
+      await linkTaskDescent(taskId, e.parent, e.relation, { client });
+      written.push(e);
+    } catch (err) {
+      skipped.push({ ...e, code: (err && err.code) || 'UNKNOWN' });
+    }
+  }
+  return { written, skipped };
+}
+
+module.exports = {
+  DESCENT_MAX_DEPTH,
+  DESCENT_RELATIONS,
+  linkTaskDescent,
+  ancestorsOfTask,
+  descendantsOfTask,
+  descendantsOfTasks,
+  deriveEdgesForTask,
+  syncDescentForTask,
+};

package/modules/ideas/migrations/ideas_007_task_descent_edges.sql

@@ -0,0 +1,111 @@
+-- ideas_007_task_descent_edges.sql — task→task provenance edges (task 1004086,
+-- BV2.R07, goal 1000095 "Working area 6"; ADR 0312).
+--
+-- WHY A SECOND TABLE AND NOT A COLUMN ON ideas_task_lineage. The spike (task
+-- 1004080) was told to confirm the lineage table rather than assume it, and
+-- confirmed one half while refuting the other. As the idea→task ANCHOR the
+-- table is right: it is bipartite, carries no depth cap and no version
+-- predicate, and so has none of the invariants that close the task hierarchy to
+-- this. But a derivation is a property of the TASK PAIR, not of the
+-- (task, idea) pair that ideas_006 made the key. Adding derived_from_task_id
+-- there would write the same derivation once per co-source idea — and
+-- co-source ideas are legal and EXPECTED since ideas_006 (merging duplicate
+-- reports into one task is the triage move the inbox exists to encourage) — so
+-- two rows for one task could disagree about where that task came from, with
+-- nothing to arbitrate. ideas_006 exists precisely because an under-keyed row
+-- silently lost attribution on prod and it took months to notice.
+--
+-- WHY NOT tasks.parent_task_id. modules/lifecycle/hierarchy.js caps parentage
+-- at ONE level and refuses cross-version trees (SELF_PARENT, VERSION_MISMATCH,
+-- PARENT_HAS_PARENT, TARGET_HAS_CHILDREN). A descent — idea → task → rewrite →
+-- split → removal — is four levels and crosses a version boundary. Both
+-- invariants are load-bearing for ship rollup and claim safety, and widening
+-- them is out of scope (spec decision 8). Provenance is a DIFFERENT RELATION
+-- from work decomposition: parent_task_id answers "what is this work part of",
+-- this table answers "where did this work come from". They are not redundant.
+--
+-- WHY IT LIVES HERE, NAMESPACED. `tasks` is the PROTECTED lifecycle module and
+-- a module migration may not ALTER a table outside its own namespace (ADR 0083
+-- §Decision #5, fitness Check 11). So this is an IDEAS-OWNED side table keyed by
+-- task ids — the same shape ideas_002 used for the same reason. FKs to existing
+-- tables are reads, not schema changes to them, so it stays inside the wall.
+--
+-- Module migrations are ADDITIVE and NAMESPACED: every object is ideas_-prefixed,
+-- no down-migration, idempotent (safe to re-run).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS ideas_task_descent (
+  -- The DERIVED task — the one that came out of something else.
+  task_id          bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- What it came FROM. A task may have SEVERAL parents: a merge folds two
+  -- pieces of work into one, so this is a DAG, not a tree. That is why the key
+  -- is the pair rather than task_id alone — the ideas_006 lesson, applied up
+  -- front instead of after an incident.
+  parent_task_id   bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- HOW it was derived. Three of these are written from signals the system
+  -- ALREADY has and currently throws away (ADR 0312): 'cascade' from the
+  -- originating id that cascade.js encodes inside source_ref as a string
+  -- nothing can join on, 'fold' from tasks.merged_into_task_id, 'split' from
+  -- tasks.parent_task_id. Only 'rewrite' and cross-version 'merge' are
+  -- editorial acts with no automatic signal, so only those depend on someone
+  -- saying so — and their absence degrades the picture rather than corrupting
+  -- it. Widen this CHECK the ideas_003 way if a sixth relation ever appears.
+  relation         text NOT NULL
+                   CHECK (relation IN ('rewrite', 'split', 'merge', 'fold', 'cascade')),
+
+  created_at       timestamptz NOT NULL DEFAULT now(),
+
+  -- A task may hold at most one edge to a given parent; several parents are fine.
+  PRIMARY KEY (task_id, parent_task_id),
+
+  -- A SELF-EDGE IS AN INFINITE WALK, NOT A COSMETIC ERROR. The payout walks
+  -- this graph (R09) and the descent reads it (R10), so a cycle does not render
+  -- oddly — it fails to terminate. This CHECK refuses the one-node case in the
+  -- schema; longer cycles cannot be expressed as a row constraint and are
+  -- refused by the writer, which walks to the root before inserting.
+  CONSTRAINT ideas_task_descent_no_self_edge CHECK (task_id <> parent_task_id)
+);
+
+-- Two directions, two indexes, because both are hot and neither is served by
+-- the other. The DESCENT walks DOWN from an origin (children of a parent); the
+-- PAYOUT walks UP from a task that just shipped (its ancestors). The primary
+-- key's implicit index already covers the (task_id, …) direction, so only the
+-- parent side needs its own.
+CREATE INDEX IF NOT EXISTS idx_ideas_task_descent_parent
+  ON ideas_task_descent (parent_task_id);
+
+-- SAFETY NET — a migration that cannot prove its own effect must not report
+-- success (the ideas_003 / ideas_005 / ideas_006 precedent). Read-only, no DDL.
+-- If the table came back without the composite key, a task could hold two
+-- contradictory edges to the same parent; if it came back without the self-edge
+-- CHECK, the first bad write hangs the payout walk instead of being refused.
+DO $$
+DECLARE pk_cols text; has_self_check boolean;
+BEGIN
+  SELECT string_agg(a.attname, ',' ORDER BY a.attname) INTO pk_cols
+    FROM pg_constraint c
+    JOIN unnest(c.conkey) AS k(attnum) ON true
+    JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
+   WHERE c.conrelid = 'ideas_task_descent'::regclass
+     AND c.contype  = 'p';
+  IF pk_cols IS DISTINCT FROM 'parent_task_id,task_id' THEN
+    RAISE EXCEPTION
+      'ideas_007: ideas_task_descent primary key is (%) — expected the composite (task_id, parent_task_id).', COALESCE(pk_cols, 'none');
+  END IF;
+
+  SELECT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conrelid = 'ideas_task_descent'::regclass
+       AND contype  = 'c'
+       AND conname  = 'ideas_task_descent_no_self_edge'
+  ) INTO has_self_check;
+  IF NOT has_self_check THEN
+    RAISE EXCEPTION
+      'ideas_007: the no-self-edge CHECK is missing — a self-edge would make the payout walk non-terminating.';
+  END IF;
+END $$;
+
+COMMIT;

package/modules/ideas/module.json

@@ -1,7 +1,7 @@
 {
   "key": "ideas",
   "title": "Ideas",
-  "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue \u2014 the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 \u00a71); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 \u00a75 \u2014 retiring the temporary `captureIdea` doorway leak).",
+  "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue — the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 §1); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 §5 — retiring the temporary `captureIdea` doorway leak).",
   "coreVersion": "^1.8.0",
   "default": true,
   "maintenance": {
@@ -11,6 +11,9 @@
     "routes": [
       "inbox",
       "blockers"
+    ],
+    "pollers": [
+      "descent-writer"
     ]
   },
   "provides": [

package/modules/ideas/pollers/descent-writer.js

@@ -0,0 +1,69 @@
+// modules/ideas/pollers/descent-writer.js — the production writer for
+// task→task provenance edges (task 1004086, BV2.R07, goal 1000095; ADR 0312).
+//
+// WHY A POLLER AND NOT A CALL FROM THE CODE THAT CAUSES THE DERIVATION. The
+// three signals ADR 0312 identified all live on `tasks`, which belongs to the
+// protected `lifecycle` module, and a module may not import another module
+// (ADR 0083, rule 1: one doorway, one direction). So cascade.js cannot call
+// into `ideas`, and `ideas` cannot reach into lifecycle's code. The published
+// doorway's `task.shipped` event is the seam that legitimately joins them, and
+// the agents module already uses it for exactly this shape of reaction
+// (modules/agents/pollers/event-router.js).
+//
+// "Poller" here means "something the module runs in the web process", not
+// "something on a clock" — it owns no timer, and the same off→on replacement
+// idiom keeps a reloaded loader from accumulating duplicate listeners, which
+// would make every ship derive its edges twice.
+//
+// A PROVENANCE EDGE MUST NEVER BREAK A SHIP. The handler is deliberately
+// total: syncDescentForTask already returns its refusals rather than throwing
+// (a refused cycle is a normal outcome, not an error), and this wraps the whole
+// call anyway. The worst failure mode available to it is a missing edge, which
+// degrades the picture. The one it must not have is a thrown error on the ship
+// path — a reactor must never break the actor.
+
+const api = require('../../../src/module-api');
+const { syncDescentForTask } = require('../descent');
+
+const log = api.logger('ideas/descent-writer');
+const EVENT = 'task.shipped';
+
+let _off = null;
+
+// The event carries the TASK ROW, the same subject modules/agents receives.
+async function onShipped(task) {
+  const taskId = task && task.id;
+  if (taskId == null) return undefined;
+  try {
+    const { written, skipped } = await syncDescentForTask(taskId);
+    if (written.length > 0 || skipped.length > 0) {
+      log.info(
+        `ideas/descent-writer: task ${taskId} — ${written.length} edge(s) recorded`
+          + (skipped.length > 0 ? `, ${skipped.length} refused` : ''),
+      );
+    }
+  } catch (err) {
+    // A reactor must never break the actor.
+    log.error(`ideas/descent-writer: derivation threw for task ${taskId}: ${err && err.message}`);
+  }
+  return undefined;
+}
+
+function start() {
+  if (_off) return;
+  _off = api.on(EVENT, onShipped);
+  log.info(`[ideas/descent-writer] listening on ${EVENT} — deriving provenance edges from source_ref, parent_task_id and merged_into_task_id`);
+}
+
+function stop() {
+  if (_off) { try { _off(); } catch (_) { /* already gone */ } }
+  _off = null;
+}
+
+module.exports = {
+  start,
+  stop,
+  // Exported for tests: the handler is the whole reaction, and it needs no
+  // server to prove.
+  onShipped,
+};

package/modules/ideas/routes/inbox.js

@@ -35,6 +35,10 @@
 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');
 // 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');
@@ -552,6 +556,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' }));