@bongos/core 1.19.904 → 1.19.905

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.904",
-  "core_contract": "1.19.904",
-  "source_commit": "a20b94f5efe38b09072d0456c5e352a2cf7bba1c",
+  "core_version": "1.19.905",
+  "core_contract": "1.19.905",
+  "source_commit": "dc5ca8cc91d1d88f957f722664f60778d2bdc4f1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T12:45:09.857Z",
+  "built_at": "2026-09-20T13:17:59.483Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 502,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2278,
+    "functional_verbatim": 2283,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2806,
-  "tree_sha256": "e03f442cd778ef6dd35a6c2f47a07e0f4d7c72a8d86882256367239d4b87989b",
+  "file_count": 2811,
+  "tree_sha256": "85790109607eeddc8439f8473f642747ed158cfb88a269f55222c30bc45016e5",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2097,12 +2097,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "3f1539c0050241b9dd7200170d664fc193c977958c2fee57e4bf5309591ccae6"
+      "sha256": "3e657714f3647bfb041f4eda9e4982a2b60747c4aceec0d8d8cbf8ee0de6eb47"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "1be015a58b02240690be5a2c5fcad56b42074500dcc7ebb8255ffa5156063748"
+      "sha256": "1ba7f556256ee4cbb637b9809698c69aff529c080131949b4055058f8fb4716b"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -2632,7 +2632,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "25f3aef34d52ca5c8a93b25fa0cd79aeba0e2395e2f66d2e192ca57464d71b65"
+      "sha256": "ade94268540de319c8d071b7b70654fca4cb4bdd7bcfbbfe8ddca5710329545b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3734,6 +3734,11 @@
       "mode": "0000644",
       "sha256": "599449a48b3850eb457a34630a7bd5d95d354602f1a9e9b887593183a457cd21"
     },
+    {
+      "path": "migrations/core_251_credit_log_idea_size_index.sql",
+      "mode": "0000644",
+      "sha256": "75bb644b32a70b52ac544edb901abff91aad07701848a470cc52103dc7e74234"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -4182,7 +4187,17 @@
     {
       "path": "modules/economy/credits.js",
       "mode": "0000644",
-      "sha256": "b0f36f5d71bc376e090b14c6c95b3ac005fecd464e59bc73213d1d3a2b662469"
+      "sha256": "736eed2c89863d6eb28072627a40ac4f8945832cfb7b1d1aba10e6cc65483901"
+    },
+    {
+      "path": "modules/economy/idea-size-historical.js",
+      "mode": "0000644",
+      "sha256": "f99f62eb4eaeda10b32284dbe27f87e64d5b6b82c9eb4aa442057d0de13be761"
+    },
+    {
+      "path": "modules/economy/idea-size.js",
+      "mode": "0000644",
+      "sha256": "d1fa5fda6b34bd2a8cf8d563c780bc4b12f1cdfb955e13f51799a589609ac1c0"
     },
     {
       "path": "modules/economy/migrations/economy_001_fix_gds_shipper_description.sql",
@@ -4207,7 +4222,7 @@
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
-      "sha256": "05f2aa731ed9bfc19088c0c6a59e0f91c6096806285e74e74b48f4530bcfa5f0"
+      "sha256": "ef4b939d83324c927dd1b1c8e3200212d0b5da973a87db6f9810c9c7edb942ad"
     },
     {
       "path": "modules/economy/routes/cost.js",
@@ -5037,7 +5052,7 @@
     {
       "path": "modules/hall-ui/public/profile.js",
       "mode": "0000644",
-      "sha256": "0ca0433fa846d12e2ea2d69084ad406d6e23fbe92e20c7364da4e92e54e26cf4"
+      "sha256": "04015850c00627f2439ec919358516c841d4c32c64a7ba18ca758b3804e804b5"
     },
     {
       "path": "modules/hall-ui/public/profile.states.json",
@@ -5377,7 +5392,7 @@
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "d4c91dcc603e4fc72ef6110a32350b2f59df19858f83a70962645a7fa09a55c4"
+      "sha256": "cd4e4d741dcbc4bb581f86aeec5b1e17dfe630712a0e5466a108daba78c74429"
     },
     {
       "path": "modules/ideas/routing.js",
@@ -5399,6 +5414,11 @@
       "mode": "0000644",
       "sha256": "2d0693b00dded081b6a0082c450762763d324d54f098a8f42a9aa25ec27370c4"
     },
+    {
+      "path": "modules/ideas/trail-size.js",
+      "mode": "0000644",
+      "sha256": "f1e60dbc8c6dc0e9f5f5cb93bf26c659422503e8ec66937a3dcee5b64971e995"
+    },
     {
       "path": "modules/lifecycle/CLAUDE.md",
       "mode": "0000644",
@@ -7762,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f6623c9d73536e00c2c9a3d44dc68f3e8bdbe44e47543c32aaa22f3059efa410"
+      "sha256": "3b60452f407da16a6c09df92482e570ca061e920dd7537a6f2f84569a13e0545"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f092d5149aa7e2518d2ddd4b940e92c4d61f8c553afedd810d97752efa9a207e"
+      "sha256": "3af5e528e00f1047c76f56189ef168ea8c879f09762b735160b5c6d2e81f9d24"
     },
     {
       "path": "public-docs/index.html",
@@ -9762,7 +9782,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f15a6c9c7458ce744ffbe72c8997b25e0098a2a26b2f6f41e7e3513fc073110d"
+      "sha256": "2489905dea4c9defd22089221f6dce7c522f9860e6b684c9e6cea03a2600a17d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11849,6 +11869,11 @@
       "mode": "0000644",
       "sha256": "3a2c5d2e6c3231f69847e1e2aea073e78caf26228b500dbdf612b5bae354d0a2"
     },
+    {
+      "path": "tests/idea_size.mjs",
+      "mode": "0000644",
+      "sha256": "c307e7c796e7e9f30b38b04144b426895642ea2d978ea5ace0f701ba7744420c"
+    },
     {
       "path": "tests/idea_spark_hall.mjs",
       "mode": "0000644",

package/docs/copy-inventory.md

@@ -308,7 +308,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `7775fec0fa85` | certain | Could not load sessions. | `modules/hall-ui/public/sessions.js:437` |
 | `a2f2e8babef5` | certain | Could not load that page. Try again. | `modules/hall-ui/public/blockers.js:274` |
 | `b2147cc90e36` | certain | Could not load the idea template. Reload, or file from the terminal with capture.js. | `modules/hall-ui/public/ideas.js:626` |
-| `7604af13c40e` | certain | Could not load the profile. | `modules/hall-ui/public/profile.js:836` |
+| `7604af13c40e` | certain | Could not load the profile. | `modules/hall-ui/public/profile.js:873` |
 | `8b69e445592a` | certain | Could not load the question labels; showing the answers as stored. | `modules/hall-ui/public/idea.js:244` |
 | `edd5bafbe075` | certain | Could not load the queue just now. | `modules/hall-ui/public/ideas.js:565` |
 | `02bb0570996a` | certain | Could not load the ranks. | `modules/hall-ui/public/ranks.js:197` |
@@ -600,7 +600,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `6e73716aec6c` | certain | May be offered for sale later | `modules/hall-ui/public/settings.html:297` |
 | `df335a1224ae` | certain | Member since {…} | `modules/hall-ui/public/hall-render.js:563` |
 | `df335a1224ae` | certain | Member since {…} | `modules/hall-ui/public/profile.js:94` |
-| `c7a670e9552d` | certain | Merged into | `modules/hall-ui/public/profile.js:452` |
+| `c7a670e9552d` | certain | Merged into | `modules/hall-ui/public/profile.js:489` |
 | `dce0546c9e34` | certain | Merging work does not put it in front of anyone. This is the step that does: it moves this platform — or any p | `modules/hall-ui/public/deploy.html:39` |
 | `7637613c231b` | certain | Metic rank and above may vote | `modules/hall-ui/public/builders.js:781` |
 | `91328a97fe68` | certain | Mingle pairs you with someone from another role. Saying no costs nothing. | `modules/hall-ui/public/collab.html:87` |
@@ -918,7 +918,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `9d4372b173cf` | certain | Standing sections | `modules/hall-ui/public/index.html:79` |
 | `ec1c2dae4a90` | certain | Standing there | `modules/hall-ui/public/profile.js:314` |
 | `eaad12cacb9d` | certain | Start over | `modules/hall-ui/public/studio.js:235` |
-| `efe530c0e3a7` | certain | Still open | `modules/hall-ui/public/profile.js:457` |
+| `efe530c0e3a7` | certain | Still open | `modules/hall-ui/public/profile.js:494` |
 | `9a4ced1afb6c` | certain | Stop waiting on task {…} | `modules/hall-ui/public/task.js:278` |
 | `b0861c874a2f` | certain | Stopped using it. | `modules/hall-ui/public/settings-specialities.js:200` |
 | `6c6544f5c011` | certain | Stored encrypted; never shown again after saving — only its last four digits. | `modules/hall-ui/public/settings.html:193` |
@@ -1352,7 +1352,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `cc5106af4b35` | certain | {…} of {…} criteria satisfied | `modules/hall-ui/public/goals-lib.js:32` |
 | `cc5106af4b35` | certain | {…} of {…} criteria satisfied | `modules/hall-ui/public/goals-render.js:682` |
 | `cc5106af4b35` | certain | {…} of {…} criteria satisfied | `modules/hall-ui/public/goals.js:45` |
-| `c3d9687e2375` | certain | {…} of {…} shipped | `modules/hall-ui/public/profile.js:558` |
+| `c3d9687e2375` | certain | {…} of {…} shipped | `modules/hall-ui/public/profile.js:595` |
 | `f32710d0ef37` | certain | {…} of {…} steps cleared. | `modules/hall-ui/public/hall-render.js:1037` |
 | `60743fe1e40d` | certain | {…} per page | `modules/hall-ui/public/hall-kit.js:74` |
 | `154bc518bab4` | certain | {…} proposed | `modules/hall-ui/public/government.js:695` |

package/docs/copy-registry.json

@@ -3815,7 +3815,7 @@
       "surface": "builders-hall",
       "text": "Could not load the profile.",
       "file": "modules/hall-ui/public/profile.js",
-      "line": 836,
+      "line": 873,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -6443,7 +6443,7 @@
       "surface": "builders-hall",
       "text": "Merged into",
       "file": "modules/hall-ui/public/profile.js",
-      "line": 452,
+      "line": 489,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9305,7 +9305,7 @@
       "surface": "builders-hall",
       "text": "Still open",
       "file": "modules/hall-ui/public/profile.js",
-      "line": 457,
+      "line": 494,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -13211,7 +13211,7 @@
       "surface": "builders-hall",
       "text": "{…} of {…} shipped",
       "file": "modules/hall-ui/public/profile.js",
-      "line": 558,
+      "line": 595,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -2282,5 +2282,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.902 with no explicit bump. run 35510679104. (task 1002620)
   1.19.904 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.903 with no explicit bump. run 35511494246. (task 1002620)
+  1.19.905 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.904 with no explicit bump. run 35513060618. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_251_credit_log_idea_size_index.sql

@@ -0,0 +1,61 @@
+-- core_251 an index for SIZE -- the per-idea rollup of the stream-1 ledger
+-- Applied under task 1004093 (BV2.R12, goal 1000095).
+--
+-- WHY. modules/economy/idea-size.js answers "what has this idea's descent
+-- paid" by summing credit_log rows whose reason embeds the idea:
+--
+--     idea.credit.task_ship:<ideaId>:<taskId>
+--
+-- That needs no column and no new table -- the ledger already carries the
+-- attribution, which is why this task needed no SCHEMA change. What it does
+-- need is a way to reach those rows without reading the whole ledger.
+--
+-- WHAT IT COSTS WITHOUT ONE. credit_log is the whole-instance, append-only
+-- credit ledger: every task payout, every session reward, every bonus, for
+-- every builder, forever. The size read runs on GET /inbox/by-builder/:id --
+-- an ordinary page view of a builder's idea trail -- so an unindexed version
+-- is a sequential scan of the entire lifetime ledger on every such view, and
+-- its cost grows with total credit events rather than with anything about the
+-- idea being looked at. A grader panel flagged exactly this on the first round
+-- of task 1004093, and it was right to.
+--
+-- THE SHAPE. A PARTIAL EXPRESSION index:
+--
+--   * the EXPRESSION is split_part(reason, ':', 2) -- the idea id, taken off
+--     the separator. The read groups on that same expression rather than on a
+--     per-idea LIKE, because a prefix match is correct only by virtue of its
+--     trailing colon and dropping it makes idea 1 absorb every payout of ideas
+--     10, 100 and 1000, silently. An index on the expression is what lets the
+--     honest form of the query stay cheap.
+--   * PARTIAL on the stream-1 prefix, so the index covers only ideator
+--     task-ship rows. Those are a small minority of credit_log: the bulk is
+--     task.shipped and session.token_reward, whose split_part(reason,':',2) is
+--     the empty string and which no size read will ever want. A full index
+--     would be several times the size to answer the same questions.
+--
+-- THE PREDICATE IS A LITERAL ON BOTH SIDES, AND THAT IS LOAD-BEARING. Postgres
+-- only uses a partial index when it can prove the query's WHERE implies the
+-- index predicate, and it cannot prove that about a parameterised
+-- `reason LIKE $1 || '%'` -- the parameter's value is not known when a generic
+-- plan is made. So idea-size.js spells the prefix into the SQL TEXT as a
+-- literal (validated at module load), matching the string below character for
+-- character. If the two ever drift, nothing errors and nothing renders
+-- differently: the index is simply never used again and the scan quietly comes
+-- back. tests/idea_size.mjs reads THIS FILE and holds its predicate against the
+-- economy constant, so the drift reds a test instead of a page.
+--
+-- THE UNDERSCORE IS ESCAPED, and it is not decoration. In LIKE, _ matches any
+-- single character, so an unescaped 'idea.credit.task_ship:%' also matches
+-- 'idea.credit.taskXship:'. No such key exists, which is precisely why nobody
+-- would ever notice; backslash is LIKE's default escape in Postgres, so no
+-- ESCAPE clause is needed and idea-size.js generates the identical string.
+--
+-- Additive and idempotent: it creates an index and touches no row. Not
+-- CONCURRENTLY -- the migration runner wraps each file in a transaction and
+-- CREATE INDEX CONCURRENTLY cannot run inside one. On an instance whose ledger
+-- is large enough for that lock to matter, build it by hand outside the runner
+-- and this statement becomes a no-op.
+
+CREATE INDEX IF NOT EXISTS idx_credit_log_idea_task_ship
+  ON credit_log ((split_part(reason, ':', 2)))
+  WHERE reason LIKE 'idea.credit.task\_ship:%';

package/modules/economy/credits.js

@@ -1273,6 +1273,14 @@ module.exports = {
   IDEA_FULL_PASS_CREDIT,
   IDEA_FULL_PASS_BAR,
   IDEA_TASK_SHIP_BASE,
+  // The two pieces of the stream-1 payout ARITHMETIC, exported for
+  // modules/economy/idea-size.js (task 1004097 / BV2.R18). A pre-existing
+  // idea backfills the payouts its descent never received, and a second copy
+  // of this arithmetic would make the backfilled figure differ from the money
+  // the same descent will earn from now on — the exact drift the
+  // ideaGradeFactor comment above exists to prevent.
+  ideaGradeFactor,
+  descentPayoutMaxDepth,
   QUICK_IDEA_FACTOR,
   IDEA_GOVERNANCE_PASS_MAX,
   IDEA_GOVERNANCE_PASS_FLOOR,

package/modules/economy/idea-size-historical.js

@@ -0,0 +1,149 @@
+'use strict';
+
+// modules/economy/idea-size-historical.js — THE HISTORICAL HALF OF SIZE
+// (task 1004097, BV2.R18, goal 1000095; spec
+// docs/specs/bongos-v2-ideator-surface.md decision 17).
+//
+// WHAT IS MISSING WITHOUT THIS, and it is not what the task title suggests.
+// A pre-existing idea's ledger figure is not ABSENT, it is PARTIAL. Stream 1's
+// direct payout has existed since ADR 0172, so a task promoted from an idea and
+// shipped since then really was paid and really is in credit_log. What never
+// happened is the DESCENT payout: awardIdeaDescentShipCredit only started
+// paying with task 1004088, so every hop below the first, for every task that
+// shipped before that, earned its origin nothing and never will.
+//
+// So the backfill is not "compute a size for ideas that have none". It is the
+// GAP between the descent an idea actually has and the part of that descent the
+// ledger was there to pay for.
+//
+// NO MONEY IS BOOKED (spec decision 17, the owner's ruling on interview Q6).
+// Nothing here writes to credit_log, and nothing here is reachable from a ship
+// path. The estimate is computed at READ time, every time, from the descent as
+// it stands. Re-paying work already paid for once is exactly what the owner
+// declined, and a backfill that wrote rows would also break stream 1's
+// idempotency key — the ledger would then hold a payment for a ship that never
+// triggered one.
+//
+// WHICH IS WHY THE TWO HALVES ARE KEPT APART RATHER THAN ADDED UP AND FORGOTTEN.
+// `paid` is money that moved; `estimated` is money that did not. A single total
+// with no marker is the number the spec calls a quiet lie, and the done-when
+// asks for the opposite — that anywhere size is shown makes clear which kind of
+// number it is. So this returns both, always, and the surfaces carry the split
+// rather than a boolean bolted on at the end.
+//
+// THE ARITHMETIC IS NOT REIMPLEMENTED HERE. `ideaGradeFactor`,
+// `descentPayoutMaxDepth` and `IDEA_TASK_SHIP_BASE` come from credits.js, which
+// is where the real payout gets them. A second copy would make an idea's
+// backfilled past disagree with the money the same descent earns from tomorrow
+// — the same drift the "EXTRACTED so the two cannot disagree" note on
+// ideaGradeFactor was written to prevent, one module over.
+
+const {
+  IDEA_TASK_SHIP_BASE,
+  ideaGradeFactor,
+  descentPayoutMaxDepth,
+} = require('./credits');
+
+// priceDescentForIdea — PURE. What one idea's descent is worth, split into the
+// part the ledger actually paid and the part it never did.
+//
+//   tasks       — every task under this idea, each { task_id, depth, status }.
+//                 Depth 0 is a task the idea was promoted INTO; depth n is n
+//                 hops below one of those. Shortest depth per task, which is the
+//                 rule the walk and the payout both already apply.
+//   grade       — the idea's grade ('quick' | 'spark' | 'full')
+//   completeness— its completeness score, or null
+//   decay       — the resolved per-instance dial (reward-policy ideaDescentDecay)
+//   paidByTask  — Map<taskIdString, creditsPaid> from credit_log, per task
+//
+// Returns { paid, estimated, payments, estimatedPayments }.
+//
+// ONLY A SHIPPED TASK COUNTS. The payout fires at ship, so a ready or abandoned
+// descendant has earned its origin nothing and estimating for it would credit
+// work that has not happened — the surface would then show a size that FELL
+// when the task was later abandoned. Everything here is anchored on ships that
+// actually occurred.
+//
+// PAID ALWAYS WINS FOR A TASK THE LEDGER KNOWS. If credit_log holds a payment
+// for (idea, task), that figure is used verbatim and no estimate is made for it
+// — money that moved is not re-derived. This is what keeps the paid half
+// immutable while the arithmetic around it is free to change: a later decay dial
+// or a re-scored completeness cannot retroactively alter what was banked.
+//
+// ROUNDED ONCE PER PAYMENT, the way the writer rounds — per (idea, task), never
+// on the total. Rounding the sum would make the backfilled figure differ from
+// what the same descent would have been paid hop by hop, which is the whole
+// thing this function exists to reproduce.
+function priceDescentForIdea({ tasks, grade, completeness, decay, paidByTask } = {}) {
+  const out = { paid: 0, estimated: 0, payments: 0, estimatedPayments: 0 };
+  const list = Array.isArray(tasks) ? tasks : [];
+  const paidMap = paidByTask instanceof Map ? paidByTask : new Map();
+
+  // A decay of 0 is a legal instance setting meaning "only the direct task
+  // pays", and it makes the cap 0 — so depth 0 is still priced and nothing
+  // below it is. Guarding on the cap rather than on the rate keeps that in one
+  // place.
+  const rate = Number.isFinite(Number(decay)) && Number(decay) >= 0 && Number(decay) < 1 ? Number(decay) : null;
+  if (rate === null) return out;
+  const maxDepth = descentPayoutMaxDepth(rate);
+  const factor = ideaGradeFactor(grade, completeness);
+
+  // One entry per task: a task reachable twice is one ship and owes one
+  // payment, at its shortest depth. The caller hands shortest-depth rows, and
+  // this keeps the guarantee local rather than trusting it.
+  const seen = new Set();
+  for (const t of list) {
+    const key = String(t && t.task_id);
+    if (!/^[1-9]\d*$/.test(key) || seen.has(key)) continue;
+    seen.add(key);
+
+    if (paidMap.has(key)) {
+      out.paid += Number(paidMap.get(key)) || 0;
+      out.payments += 1;
+      continue;
+    }
+
+    if (t.status !== 'shipped') continue;
+    const depth = Number(t.depth);
+    if (!Number.isInteger(depth) || depth < 0) continue;
+    // Depth 0 is the direct payout at full share; below that the cap applies,
+    // because past it even a perfect idea's decayed share rounds away.
+    if (depth > 0 && (rate === 0 || depth > maxDepth)) continue;
+    const delta = Math.round(IDEA_TASK_SHIP_BASE * factor * Math.pow(rate, depth));
+    if (delta <= 0) continue;
+    out.estimated += delta;
+    out.estimatedPayments += 1;
+  }
+  return out;
+}
+
+// descentRowsFromTrail — the tasks under an idea, as the TRAIL already holds
+// them. Pure, and deliberately not a walk.
+//
+// modules/ideas/trail-descent.js has already walked the whole page by the time
+// size is attached (the route composes them in that order), so the trail path
+// re-uses that result and costs no extra round trip at all. `lineage_tasks` are
+// the idea's own tasks — depth 0, the full-share hop — and `descent_tasks` are
+// everything below them, already carrying their shortest depth and their status.
+//
+// A lineage row that also appears in the descent is dropped by the depth-0 entry
+// winning: the Set in priceDescentForIdea keeps the first sighting, and the
+// direct tasks are emitted first for exactly that reason.
+function descentRowsFromTrail(idea) {
+  const rows = [];
+  const direct = Array.isArray(idea && idea.lineage_tasks) ? idea.lineage_tasks : [];
+  for (const t of direct) rows.push({ task_id: t.task_id, depth: 0, status: t.status });
+  // The legacy single-FK promotion, for rows that predate ideas_task_lineage —
+  // the same fallback the trail and trail-descent both apply.
+  if (direct.length === 0 && idea && idea.promoted_to_task_id != null) {
+    rows.push({ task_id: idea.promoted_to_task_id, depth: 0, status: idea.promoted_task_status ?? null });
+  }
+  const below = Array.isArray(idea && idea.descent_tasks) ? idea.descent_tasks : [];
+  for (const t of below) rows.push({ task_id: t.task_id, depth: t.depth, status: t.status });
+  return rows;
+}
+
+module.exports = {
+  priceDescentForIdea,
+  descentRowsFromTrail,
+};