@bongos/core 1.19.901 → 1.19.903

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);

package/tests/plain_cards.mjs

@@ -107,7 +107,7 @@ test('every card is complete, and short enough to be read', () => {
 
 test('the restrictions that must never be worked around are marked by_design', () => {
   for (const code of ['REBASE_REQUIRED', 'INSUFFICIENT_RANK', 'rank_too_low_for_task', 'session_already_has_active_claim',
-    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'box_scope', 'no_push_credential', 'grade_refused_authorization']) {
+    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'no_push_credential', 'grade_refused_authorization']) {
     assert.equal(cardFor(code)?.by_design, true, code);
   }
   assert.match(cardFor('no_push_credential').next, /never ask/i);
@@ -164,7 +164,7 @@ test('a person at a terminal gets no card — it is written in the agent\'s voic
 
 test('the sign-in printers, the release refusals and the claim guard each print their card', () => {
   const wired = {
-    'scripts/gds/cli-lib.js': ['session_invalid', 'box_scope', 'no_session'],
+    'scripts/gds/cli-lib.js': ['session_invalid', 'no_session'],
     'scripts/gds/release.js': ['no_active_claim', 'CLAIM_SESSION_MISMATCH'],
     'scripts/gds/claim.js': ['main_checkout_claim'],
     'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked'],

package/tests/rank_tier_single_source.mjs

@@ -12,7 +12,7 @@
 //      modules/discord/discord-channels.js): dependency-free substrate
 //      (permission-path-check runs in a bare git hook), source-parsed literals
 //      (src/bongos/db.js — gate-review.js + diagram-facts.js regex its text),
-//      standalone CLIs (sequence, box-connect-lib), the require-free dev-box
+//      standalone CLIs (sequence), the require-free dev-box
 //      module template (boxes.js), zero-dep catalog + its text-parsing auditor
 //      (route-rank-check), and the hall browser statics.
 //   3. NO NEW parallel map can land: a repo scan flags any rank→number map or
@@ -38,7 +38,6 @@ const lifecycleDb = require(path.join(ROOT, 'modules', 'lifecycle', 'db.js'));
 const ppc = require(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'));
 const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
 const sequence = require(path.join(ROOT, 'scripts', 'gds', 'sequence.js'));
-const boxConnect = require(path.join(ROOT, 'scripts', 'gds', 'box-connect-lib.js'));
 const boxes = require(path.join(ROOT, 'modules', 'dev-box', 'boxes.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
 
@@ -82,8 +81,8 @@ test('1-based local copies match: permission-path-check, sequence CLI', () => {
   assert.deepEqual(sequence.RANK_TIER, TIER, 'sequence.js CLI copy drifted');
 });
 
-test('0-based local copies match: box-connect-lib CLI, dev-box boxes.js', () => {
-  for (const [name, map] of [['box-connect-lib', boxConnect.RANK_ORDER], ['boxes', boxes.RANK_ORDER]]) {
+test('0-based local copies match: dev-box boxes.js', () => {
+  for (const [name, map] of [['boxes', boxes.RANK_ORDER]]) {
     assert.deepEqual(Object.keys(map).sort(), [...RANK_KEYS].sort(), `${name} keys drifted`);
     for (const r of RANK_KEYS) {
       assert.equal(map[r], TIER[r] - 1, `${name}.RANK_ORDER.${r} must be tier-1 (0-based)`);
@@ -193,7 +192,6 @@ const MAP_ALLOWLIST = new Set([
   'src/bongos/db.js',
   'src/bongos/permission-path-check.js',
   'scripts/gds/sequence.js',
-  'scripts/gds/box-connect-lib.js',
   'modules/dev-box/boxes.js',
   'modules/hall-ui/public/builders.js',
   // task 1003206 carved the hall page scripts up. builders.js KEPT its map (the