@bongos/core 1.19.900 → 1.19.901

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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.900",
+  "version": "1.19.901",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.900",
+      "version": "1.19.901",
       "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.901",
   "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",

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.901'; // 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_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: [] };
     },
   };