@bongos/core 1.19.901 → 1.19.902

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.901",
-  "core_contract": "1.19.901",
-  "source_commit": "eaeb90f6f672cebb32a56069fe0f4cdab41c983a",
+  "core_version": "1.19.902",
+  "core_contract": "1.19.902",
+  "source_commit": "2ec480ac926f1b9c899eef2576b1e6a7409e9013",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T06:23:47.726Z",
+  "built_at": "2026-09-20T07:49:00.223Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 502,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2283,
+    "functional_verbatim": 2284,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2811,
-  "tree_sha256": "c3fd3f2ffac72933f622b7cb06be2429710627f38d9a3d541cb1ce7f595cdf6a",
+  "file_count": 2812,
+  "tree_sha256": "e1c4784e88618bc042732cabcda2e40e5af8c8a4f21282de67baa72990fe7b6b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2632,7 +2632,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "3ff6099cba4fdc3c31689aa4f007bdb23a8aa5fca100f118eb817e44cf8986c0"
+      "sha256": "367d63ea84eaa28d8ccbadc967d41fb94a689906a8d8438e8b6a123c6ff4489e"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4182,7 +4182,7 @@
     {
       "path": "modules/economy/credits.js",
       "mode": "0000644",
-      "sha256": "ec69c40c89a3bb5f49dae8c04076646c972d1ed21d3b556ed6bc492dd15628c7"
+      "sha256": "b0f36f5d71bc376e090b14c6c95b3ac005fecd464e59bc73213d1d3a2b662469"
     },
     {
       "path": "modules/economy/migrations/economy_001_fix_gds_shipper_description.sql",
@@ -4202,12 +4202,12 @@
     {
       "path": "modules/economy/reward-policy.js",
       "mode": "0000644",
-      "sha256": "e1f432cc9871bcb992face1f8ecd9f63fea17b3b67c121d59e8e28a89ba8d7d5"
+      "sha256": "817f400faa29aabcfdeb98eabeca45790203dff2dbca2ed01336d69078dd2be2"
     },
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
-      "sha256": "c4245b1b7c361eb44e0034f19227e208b956e9eb9ac03924e22b3017dd4a343a"
+      "sha256": "05f2aa731ed9bfc19088c0c6a59e0f91c6096806285e74e74b48f4530bcfa5f0"
     },
     {
       "path": "modules/economy/routes/cost.js",
@@ -5362,7 +5362,7 @@
     {
       "path": "modules/ideas/module.json",
       "mode": "0000644",
-      "sha256": "d78cc041fcd92485e38684a216a846e163ea443a8afea9f304aca3a2ac086d4d"
+      "sha256": "c23099e7c3a4768dc68778292c42988ee21234ed81d1832347e9fd272f6137d9"
     },
     {
       "path": "modules/ideas/pollers/descent-writer.js",
@@ -5377,7 +5377,7 @@
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "5324f8d2eb8d55decadd371f2c48ee141e88b9aa3d62de0921d467aef401c2ae"
+      "sha256": "d4c91dcc603e4fc72ef6110a32350b2f59df19858f83a70962645a7fa09a55c4"
     },
     {
       "path": "modules/ideas/routing.js",
@@ -5517,7 +5517,7 @@
     {
       "path": "modules/lifecycle/db-ship.js",
       "mode": "0000644",
-      "sha256": "fc65aa01818dcd8c74d013e074ff9b6c71c34537230fc844e6a23b69cc93e22f"
+      "sha256": "14c269ad1bf569976421c71e0814d47338bd11f9382e9949e2e01f6f6f15f6c7"
     },
     {
       "path": "modules/lifecycle/db-tasks.js",
@@ -7762,12 +7762,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "81176248d1045cd137a823208e30bdf4907b4f08ae1c0c0ff85750a38d2aeed3"
+      "sha256": "b072b5799f9a792ea474fc50364b099b477a89037abac29f31a80a4e0afd56a4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bff9286aa9803a2eedaffb0f0798fcd15a27791208c786a6544424aa04db4a16"
+      "sha256": "70ca20ce45a63886eff37d367e9574ab1ecc6d77191d500bc9c080ac80e71f8a"
     },
     {
       "path": "public-docs/index.html",
@@ -9777,7 +9777,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5ac46b294e25abc7c2a076f538a123991a638f3069dd4980ba2b75392942b710"
+      "sha256": "46c60fef08ac1cdeedec15a52a867d37f30a61e0ddbf9092a489fc7f5eae3a01"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11814,6 +11814,11 @@
       "mode": "0000644",
       "sha256": "3e43b2afa7ea9e8ccee99759c27f7ab28f7a49823cc3b7e921071714d2d0d7f1"
     },
+    {
+      "path": "tests/idea_descent_ship_credit.mjs",
+      "mode": "0000644",
+      "sha256": "e2bc31f771f80549cf50f9614b5473485f6c9db9b9179f3830a76738e1247ac7"
+    },
     {
       "path": "tests/idea_detail_page.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2276,5 +2276,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.899 with no explicit bump. run 35492534307. (task 1002620)
   1.19.901 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.900 with no explicit bump. run 35494090938. (task 1002620)
+  1.19.902 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.901 with no explicit bump. run 35497860558. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/economy/credits.js

@@ -9,7 +9,7 @@
 // (db.applyGrade/confirmTask/upsertSessionRecordWithReward) resolves these
 // through the `reward` kernel PORT rather than importing this module.
 
-const { pool, branding } = require('../../src/module-api');
+const { pool, branding, resolveOptional } = require('../../src/module-api');
 const { priceModelUsage, PRICES } = require('../../src/module-api').llmPricing; // cost-plus session reward (task 1005)
 const achievements = require('./achievements');
 
@@ -157,7 +157,7 @@ const IDEA_GOVERNANCE_PASS_FLOOR = 30;  // owner: floor ~30 — see the note on
 // Re-exported below, so this module is still the one place reward resolution lives
 // (ADR 0146) and every existing caller is unchanged.
 const {
-  REWARD_MARGIN_PCT, REWARD_MODE_DEFAULT, REWARD_MODE_COST_PLUS_ONLY, rewardPolicy,
+  REWARD_MARGIN_PCT, REWARD_MODE_DEFAULT, REWARD_MODE_COST_PLUS_ONLY, IDEA_DESCENT_DECAY, rewardPolicy,
 } = require('./reward-policy');
 
 // Per-instance reward policy, resolved over the code defaults. Stays HERE, not in
@@ -502,6 +502,40 @@ async function awardIdeaFullPassCredit(client, { ideaId, authorId, completenessS
   };
 }
 
+// descentPayoutMaxDepth — the deepest hop that can still pay a single credit.
+//
+// The decayed share is base × factor × decay^d, and the best case for factor is
+// 1 (a 100%-complete Full Idea). Once that rounds to 0 no deeper ancestor can
+// ever be paid, whatever its grade, so walking further is pure round trips.
+// Returned as a DEPTH CAP for the walk rather than a break in the payout loop,
+// because the round trips happen inside the walk, not in the loop.
+//
+// Derived, never picked: at the default half it comes out at 4, and a steeper
+// rate gives a smaller number. DESCENT_MAX_DEPTH remains the outer backstop.
+function descentPayoutMaxDepth(decay, base = IDEA_TASK_SHIP_BASE, cap = 64) {
+  if (!(decay > 0)) return 0;
+  for (let d = 1; d <= cap; d += 1) {
+    if (Math.round(base * Math.pow(decay, d)) <= 0) return d - 1;
+  }
+  return cap;
+}
+
+// ideaGradeFactor — what one shipped task under an idea is worth, BEFORE depth.
+//
+// A Full Idea earns in proportion to its completeness; a Quick or Spark idea
+// (no completeness score) earns the flat quick factor. A full idea with no score
+// yet also falls back to the quick factor rather than 0 — the work shipped, and
+// the idea is at least quick-grade.
+//
+// EXTRACTED so the direct payout and the decayed descent payout below cannot
+// disagree about what an idea's work is worth: the two differ only by the decay
+// term, and a second copy of this clamp would make them differ by more.
+function ideaGradeFactor(grade, completeness) {
+  return (grade === 'full' && completeness != null && Number.isFinite(Number(completeness)))
+    ? Math.max(0, Math.min(1, Number(completeness) / 100))
+    : QUICK_IDEA_FACTOR;
+}
+
 // Stream 1 (ADR 0172 / goal 1000067 IC4): as each task descended from an idea
 // SHIPS, pay the idea's author IDEA_TASK_SHIP_BASE credits, SCALED by the idea's
 // grade — a Full Idea by its completeness, a Quick/Spark idea by a flat factor.
@@ -560,13 +594,7 @@ async function awardIdeaTaskShipCredit(client, { taskId, config = rewardConfig()
     return { credited: 0, reason: 'no_source_idea', ideaId: null, authorId: null };
   }
   const { idea_id: ideaId, captured_by: authorId, grade, completeness, developed_by: developedBy } = rows[0];
-  // Grade factor: a Full Idea earns in proportion to its completeness; a Quick
-  // or Spark idea (no completeness score) earns the flat quick factor. A full
-  // idea with no score yet also falls back to the quick factor rather than 0 —
-  // the work shipped, the idea is at least quick-grade.
-  const factor = (grade === 'full' && completeness != null && Number.isFinite(Number(completeness)))
-    ? Math.max(0, Math.min(1, Number(completeness) / 100))
-    : QUICK_IDEA_FACTOR;
+  const factor = ideaGradeFactor(grade, completeness);
   const delta = Math.round(IDEA_TASK_SHIP_BASE * factor);
   if (delta <= 0) {
     return { credited: 0, reason: 'zero_after_scaling', ideaId: Number(ideaId), authorId: Number(authorId) };
@@ -592,6 +620,184 @@ async function awardIdeaTaskShipCredit(client, { taskId, config = rewardConfig()
     : { credited: 0, reason: 'already_paid', ideaId: Number(ideaId), authorId: Number(authorId) };
 }
 
+// awardIdeaDescentShipCredit — the same stream 1 payout, for the origins the
+// shipping task descends from RATHER THAN the one it was promoted from
+// (task 1004088, BV2.R09; ADR 0312, spec decisions 6 + 7 + 16).
+//
+// WHAT WAS MISSING. awardIdeaTaskShipCredit above pays the idea whose
+// ideas_task_lineage row names THIS task. That is one hop. A task split off a
+// task an idea produced, a cascade its ship fired, a child of a child — all of
+// them ship and pay the origin nothing, because the origin is not on their
+// lineage row and never will be. The idea's descent grew; its ledger did not.
+//
+// THE RULE: full share at the direct task, `decay` per hop below it. At the
+// default half, an unbounded descent is worth at most twice the direct task, so
+// the series converges and no hop limit has to be invented. The rate is a
+// per-instance dial (config.ideaDescentDecay; modules/economy/reward-policy.js).
+//
+// THE BOUNDARY THAT STOPS FARMING (spec decision 7): DESCENDANT WORK pays the
+// origin; a separate thought that merely cites it does not. Nothing here reads
+// an idea→idea relation — not merged_into_idea_id, not the trail's merge follow.
+// It walks ideas_task_descent, which carries only task→task edges the system
+// derived from a cascade, a split or a fold. That asymmetry is deliberate and is
+// the difference between the two surfaces: the descent DISPLAYS more than the
+// payout COUNTS.
+//
+// ONE PAYMENT PER ORIGIN PER SHIP, AT THE SHORTEST DEPTH. A merge makes the
+// descent a DAG, so one origin can sit above a shipping task by two routes of
+// different length, and two ancestors can share a source idea. Each origin is
+// therefore resolved once, at the smallest depth — the same rule the walk itself
+// applies, for the same reason: at two depths it would be paid twice for one
+// piece of work. The reason key is already per (idea, task), so the ledger would
+// have caught the duplicate; resolving it here means the RETURNED numbers are
+// right too, rather than depending on which booking ran first.
+//
+// FAIL-SOFT AROUND THE WALK, NOT AROUND THE MONEY. If the ideas module is absent
+// (no provider) or has no edges yet, this returns nothing paid and the direct
+// payout above is untouched — which is exactly today's behaviour, and is what
+// "existing first-hop behaviour preserved" means. A walk that THROWS is a
+// different matter and is left to propagate: this runs inside the ship
+// transaction beside the direct credit, and silently swallowing a failure here
+// would under-pay an origin with no record that it happened.
+//
+//   client   — pg client / pool (transaction participant)
+//   taskId   — the task that just shipped
+//   skipIdeaIds — origins already paid for this ship at depth 0, so the direct
+//                 payout always wins over a decayed one for the same idea
+//   config   — resolved reward policy; gates on config.ideatorCredit
+//
+// Returns { credited, reason, payments: [{ ideaId, depth, delta, payees }] }.
+async function awardIdeaDescentShipCredit(client, { taskId, skipIdeaIds = [], config = rewardConfig() } = {}) {
+  if (config && config.ideatorCredit === false) {
+    return { credited: 0, reason: 'ideator_lane_off', payments: [] };
+  }
+  // BOUNDED HERE TOO, not only in rewardPolicy(). This is a PORT method: the
+  // reward port hands it to any module that resolves it, and a caller may pass
+  // its own `config` object that never went through the resolver. A rate of 1
+  // or more does not converge — the comment on IDEA_DESCENT_DECAY promises it
+  // cannot happen, and a promise the function does not enforce is a promise the
+  // next caller breaks. Out of range falls back to the default, exactly as the
+  // resolver does, rather than throwing inside a ship transaction.
+  const rawDecay = (config && config.ideaDescentDecay) == null
+    ? NaN
+    : Number(config.ideaDescentDecay);
+  const decay = Number.isFinite(rawDecay) && rawDecay >= 0 && rawDecay < 1
+    ? rawDecay
+    : IDEA_DESCENT_DECAY;
+  // 0 means "only the direct task pays" — a legal instance setting, and the
+  // cheapest possible answer, so it short-circuits before the walk.
+  if (!(decay > 0)) return { credited: 0, reason: 'decay_off', payments: [] };
+
+  // The walk lives in the ideas module and is reached through the switchboard:
+  // a module may not require a sibling (ADR 0083 rule 1), and a second copy of
+  // a breadth-first shortest-depth walk would drift into a different amount of
+  // money. resolveOptional, because an instance running without the ideas
+  // module has no descent to follow and must still ship tasks.
+  const port = resolveOptional && resolveOptional('ideas.descent');
+  if (!port || typeof port.ancestorsOfTask !== 'function') {
+    return { credited: 0, reason: 'no_descent_port', payments: [] };
+  }
+  // DON'T WALK FURTHER THAN THE MONEY REACHES. Past the depth at which even a
+  // 100%-complete idea's decayed share stops rounding to a credit, every
+  // remaining hop is a round trip that provably pays nobody. The cap is derived
+  // from the rate rather than picked: at the default half it is 4, and a
+  // shallower rate makes it smaller, not larger. Bounded by the walk's own
+  // DESCENT_MAX_DEPTH, which stays the backstop.
+  const maxDepth = descentPayoutMaxDepth(decay);
+  const ancestors = await port.ancestorsOfTask(taskId, { client, maxDepth });
+  if (!ancestors || ancestors.length === 0) {
+    return { credited: 0, reason: 'no_ancestors', payments: [] };
+  }
+
+  // The shortest depth at which each ancestor TASK sits above this ship.
+  // ancestorsOfTask already returns nearest-first with each node once, so the
+  // first sighting is the shortest; the map is here so the lookup below cannot
+  // accidentally read a later one.
+  const depthByTask = new Map();
+  for (const a of ancestors) {
+    const key = String(a.id);
+    if (!depthByTask.has(key)) depthByTask.set(key, a.depth);
+  }
+
+  // Which idea each ancestor task came from — ONE query, not one per ancestor.
+  // DISTINCT ON picks the EARLIEST lineage link per task, which is the same rule
+  // awardIdeaTaskShipCredit applies to the direct task (task 1003515 / ADR 0236:
+  // a task subsumed from several ideas keeps a row for each, so the read must
+  // choose, and it must choose the way the trail and inbox.sourceIdeaForTask do
+  // or the ledger and the money name different ideas).
+  const { rows } = await client.query(
+    `SELECT DISTINCT ON (l.task_id)
+            l.task_id,
+            l.idea_id,
+            i.captured_by,
+            COALESCE(g.grade, 'quick')        AS grade,
+            g.completeness_score              AS completeness,
+            g.developed_by                    AS developed_by
+       FROM ideas_task_lineage l
+       JOIN idea_inbox i        ON i.id = l.idea_id
+       LEFT JOIN ideas_grades g ON g.idea_id = l.idea_id
+      WHERE l.task_id = ANY($1::bigint[])
+      ORDER BY l.task_id, l.created_at ASC, l.idea_id ASC`,
+    [[...depthByTask.keys()].map(Number)]
+  );
+
+  // Collapse ancestor tasks onto their ORIGINS: two ancestors can share one
+  // source idea, and that idea is owed one payment at the shallower of the two.
+  const skip = new Set((skipIdeaIds || []).map(String));
+  const byIdea = new Map();
+  for (const row of rows) {
+    if (row.captured_by == null) continue;
+    const ideaKey = String(row.idea_id);
+    if (skip.has(ideaKey)) continue;          // already paid in full at depth 0
+    const depth = depthByTask.get(String(row.task_id));
+    if (!Number.isInteger(depth) || depth < 1) continue;
+    const prev = byIdea.get(ideaKey);
+    if (prev && prev.depth <= depth) continue;
+    byIdea.set(ideaKey, { row, depth });
+  }
+
+  const payments = [];
+  let credited = 0;
+  // Nearest origins first, so a partially-booked run resumes in a stable order
+  // and the returned list reads the way the descent does.
+  const ordered = [...byIdea.values()].sort((a, b) => a.depth - b.depth || Number(a.row.idea_id) - Number(b.row.idea_id));
+  for (const { row, depth } of ordered) {
+    const { idea_id: ideaId, captured_by: authorId, grade, completeness, developed_by: developedBy } = row;
+    // The SAME grade factor the direct payout applies — a Full Idea earns in
+    // proportion to its completeness, a Quick or Spark idea the flat factor.
+    // Spelled through the shared helper so the two paths cannot disagree about
+    // what an idea's work is worth before depth is taken into account.
+    const factor = ideaGradeFactor(grade, completeness);
+    // ROUNDED ONCE, at the end. Rounding per hop would compound the error, and
+    // rounding to zero IS the floor the spec's open question asked about: a
+    // descendant stops paying when its decayed share no longer rounds to a
+    // credit, which needs no separately-chosen hop limit.
+    const delta = Math.round(IDEA_TASK_SHIP_BASE * factor * Math.pow(decay, depth));
+    if (delta <= 0) continue;
+    const payees = splitIdeaCredit(delta, { authorId, developedBy });
+    if (payees.length === 0) continue;
+    // THE SAME REASON KEY the direct payout uses — per (idea, task), not per
+    // (idea, task, depth). An origin is paid once for one ship however the
+    // descent is re-walked, and a re-run after a partial failure is safe.
+    const reason = `idea.credit.task_ship:${ideaId}:${taskId}`;
+    const gradeLabel = `${grade}${completeness != null ? ` ${Math.round(Number(completeness))}%` : ''}`;
+    const { credited: paid, payees: booked } = await bookIdeaSplit(client, {
+      payees,
+      reason,
+      taskId,
+      describe: (p) => `Task #${taskId} shipped ${depth} hop${depth === 1 ? '' : 's'} below idea #${ideaId} (${gradeLabel}) → ${p.delta}c to its ${p.role.replace(/_/g, ' ')} (ideator lane stream 1, decayed by depth, BV2.R09/ADR 0312)`,
+    });
+    credited += paid;
+    payments.push({ ideaId: Number(ideaId), depth, delta, credited: paid, payees: booked });
+  }
+
+  return {
+    credited,
+    reason: credited > 0 ? 'paid' : (payments.length > 0 ? 'already_paid' : 'nothing_to_pay'),
+    payments,
+  };
+}
+
 // Stream 3 (ADR 0172 / goal 1000067 IC5): a Full Idea that PASSES the Board
 // Room's ratification vote pays a share of a 100-credit ceiling, scaled by the
 // idea's R142 completeness — "70%-complete + passes = 70". The ideator lane, so
@@ -1059,6 +1265,7 @@ module.exports = {
   maybeAwardIdeaPromotionBonus,
   awardIdeaFullPassCredit,
   awardIdeaTaskShipCredit,
+  awardIdeaDescentShipCredit,
   awardIdeaGovernancePassCredit,
   // the spark-handoff split (task 1002923 / BV1.R147, ADR 0185)
   splitIdeaCredit,

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/ideas/module.json

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

package/modules/ideas/routes/inbox.js

@@ -39,6 +39,8 @@ const inbox = require('../inbox');
 // 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');
@@ -61,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 —

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

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.901'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.902'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/idea_descent_ship_credit.mjs

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