@bongos/core 1.19.904 → 1.19.905

package/tests/idea_size.mjs

@@ -0,0 +1,776 @@
+// tests/idea_size.mjs
+//
+// task 1004093 (BV2.R12, goal 1000095) — SIZE: an idea's total ideator payout
+// from its descent, computable from the ledger for any idea, compressed for
+// drawing, with the true figure kept. Spec
+// docs/specs/bongos-v2-ideator-surface.md decisions 4, 5 and 7.
+//
+// WHAT CAN GO SILENTLY WRONG HERE, which is what this file is aimed at:
+//
+//   * THE PREFIX BOUNDARY. The reason key is `idea.credit.task_ship:<idea>:
+//     <task>`, so "idea 1's payouts" as a naive prefix match swallows every
+//     payout of ideas 10, 100 and 1000. Nothing errors; one star is simply
+//     drawn enormous. The read groups on the SEPARATOR instead, and §2 pins
+//     both the behaviour and the shape of the SQL that delivers it.
+//   * THE WRONG STREAM. Streams 2 and 3 (`full_pass`, `governance_pass`) book
+//     under keys that embed the same idea id, and they pay for the THOUGHT, not
+//     for the work it caused. Counting them makes a well-written idea that
+//     caused nothing draw like one that caused a version.
+//   * A RELATIVE SCALE. Compressing against the biggest idea on screen draws
+//     better and destroys the one property size exists to have — it would FALL
+//     when a bigger thought appeared beside it, with no credit changing hands.
+//   * SIZE FALLING. The invariant is claimed in the module header, so it is
+//     tested where it actually lives — in the WRITERS (§4), by driving the real
+//     credits.js payout paths and asserting nothing non-positive is ever booked
+//     under this prefix. A property a comment asserts and no test drives is a
+//     comment.
+//   * A DORMANT FIELD. §5 and §6 run the real read into the real consumers —
+//     the trail attach, and then the real profile page — with nothing
+//     hand-built in between.
+//
+// DB-free. The ledger client is a stub, so §2 can only prove the ARITHMETIC
+// against a faithful twin of the predicate; the SQL TEXT is therefore pinned
+// separately, clause by clause, so the twin cannot quietly diverge from it.
+//
+// Run:  node tests/idea_size.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';
+import { bootProfilePage, settle } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ideaSizeLib = require('../modules/economy/idea-size.js');
+const credits = require('../modules/economy/credits.js');
+const reward = require('../modules/economy/reward.js');
+const trailSize = require('../modules/ideas/trail-size.js');
+const api = require('../src/module-api.js');
+const { rewardPolicy } = 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))}`); }
+}
+
+const PREFIX = credits.IDEA_STREAM_REASON_PREFIXES.task_ship;
+
+// ---------------------------------------------------------------------------
+// the ledger stub
+// ---------------------------------------------------------------------------
+
+// A twin of the read's predicate, applied to a fixture ledger — and it READS
+// THE STATEMENT rather than reimplementing it from memory. Both load-bearing
+// decisions are lifted out of the SQL text: which colon-delimited field the
+// idea id comes from (`split_part(reason, ':', N)`), and whether the stream-1
+// prefix is actually being applied (the `reason LIKE` clause). That is what
+// makes these arithmetic tests bite on the real query: change the field index
+// or drop the stream guard and the twin changes with it, so §2 reds instead of
+// agreeing with a stale copy of the rule.
+function ledgerClient(rows) {
+  const log = [];
+  return {
+    log,
+    async query(sql, params) {
+      log.push({ sql, params });
+      if (!/FROM credit_log/i.test(sql)) return { rows: [] };
+      const field = /split_part\(reason, ':', (\d+)\)/.exec(sql);
+      assert.ok(field, 'the read must take the idea id off the separator — the twin follows the SQL, not a memory of it');
+      const idx = Number(field[1]) - 1;
+      // The stream guard is a LITERAL in the statement (so the partial index can
+      // be chosen), so the twin reads it out of the SQL rather than off a param.
+      // Unescaped back to the literal the writers use: the statement escapes
+      // LIKE's _ wildcard, so a twin comparing the raw form would match nothing.
+      const guard = /reason LIKE '([^']*)%'/.exec(sql);
+      const prefix = guard && guard[1].replace(/\\([\\%_])/g, (m, ch) => ch);
+      const ids = (params[0] || []).map(String);
+      // Grouped per (idea, task) since BV2.R18 — the per-task breakdown is what
+      // tells the backfill which hops the ledger already paid for. The twin
+      // follows the statement here too: it groups by whatever GROUP BY names.
+      const byTask = /GROUP BY 1, 2/.test(sql);
+      const grouped = new Map();
+      for (const row of rows) {
+        if (prefix && !String(row.reason).startsWith(prefix)) continue;
+        const parts = String(row.reason).split(':');
+        const ideaId = parts[idx];
+        if (!ids.includes(ideaId)) continue;
+        const taskId = row.task_id != null ? String(row.task_id) : parts[2];
+        const key = byTask ? `${ideaId}|${taskId}` : ideaId;
+        const acc = grouped.get(key) || { idea_id: ideaId, task_id: byTask ? taskId : null, credits: 0, payments: 0 };
+        acc.credits += Number(row.delta);
+        acc.payments += 1;
+        grouped.set(key, acc);
+      }
+      return { rows: [...grouped.values()] };
+    },
+  };
+}
+
+const paid = (ideaId, taskId, delta) => ({ reason: `${PREFIX}${ideaId}:${taskId}`, delta });
+
+// ---------------------------------------------------------------------------
+// 0. BEFORE any port exists — the unknown-historical state
+// ---------------------------------------------------------------------------
+
+// FIRST, and it has to be: a port is single-provider and cannot be unregistered
+// (src/module-seams.js), so the only honest place to test the absent-walk branch
+// is before anything registers one. The idea_descent_ship_credit.mjs precedent.
+await test('with no descent port and no caller map, the historical half is NULL — not zero', async () => {
+  // Third state, and it must not render as either of the other two: "nothing was
+  // estimated" and "we could not look" are different answers, and only one of
+  // them may be drawn as a plain figure.
+  assert.equal(api.hasProvider('ideas.descent'), false, 'nothing has registered the walk yet');
+  const c = ledgerClient([paid(7, 500, 5)]);
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c })).get('7');
+  assert.equal(size.paid, 5, 'what was actually paid is still known');
+  assert.equal(size.estimated, null);
+  assert.equal(size.historical, null, 'unknown is not false');
+  assert.equal(size.credits, 5);
+});
+
+// ---------------------------------------------------------------------------
+// 1. the compression — pure, absolute, monotonic
+// ---------------------------------------------------------------------------
+
+await test('an idea that has earned nothing compresses to a clean zero', () => {
+  assert.equal(ideaSizeLib.compressIdeaSize(0), 0);
+  assert.equal(ideaSizeLib.compressIdeaSize(null), 0, 'and a missing figure is not negative infinity');
+  assert.equal(ideaSizeLib.compressIdeaSize('nonsense'), 0);
+  assert.equal(ideaSizeLib.compressIdeaSize(-5), 0);
+});
+
+await test('the compression is MONOTONIC — more credits never draws smaller', () => {
+  let prev = -1;
+  for (const c of [0, 1, 2, 5, 10, 25, 50, 100, 250, 500, 5000]) {
+    const s = ideaSizeLib.compressIdeaSize(c);
+    assert.ok(s >= prev, `${c} credits must not draw smaller than the step below it`);
+    prev = s;
+  }
+});
+
+await test('it is bounded to [0,1] and SATURATES rather than running away', () => {
+  assert.equal(ideaSizeLib.compressIdeaSize(ideaSizeLib.IDEA_SIZE_SCALE_REF), 1);
+  assert.equal(ideaSizeLib.compressIdeaSize(1e9), 1, 'the drawing has a ceiling; the true figure does not');
+});
+
+await test('it COMPRESSES — the long tail is not allowed to eat the picture', () => {
+  // 100x the credits must not be 100x the drawn magnitude, or a single large
+  // idea renders every other thought in the project as the same dot.
+  const small = ideaSizeLib.compressIdeaSize(5);
+  const large = ideaSizeLib.compressIdeaSize(500);
+  assert.ok(large / small < 10, `500c draws ${(large / small).toFixed(1)}x a 5c idea, not 100x`);
+  assert.ok(large > small, 'while still being visibly bigger');
+});
+
+await test('the scale is ABSOLUTE, not relative to whoever else is on screen', async () => {
+  // THE PROPERTY SIZE EXISTS TO HAVE. An idea's drawn magnitude must be the same
+  // number whether it is read alone or beside a thought ten times its size — a
+  // set-relative normalisation would make it FALL when a bigger star appeared,
+  // which is brightness's job (BV2.R16) and never size's.
+  const alone = await ideaSizeLib.ideaSizes(['7'], { client: ledgerClient([paid(7, 500, 5)]) });
+  const crowded = await ideaSizeLib.ideaSizes(['7', '8'], {
+    client: ledgerClient([paid(7, 500, 5), paid(8, 501, 400)]),
+  });
+  assert.equal(alone.get('7').scale, crowded.get('7').scale,
+    'the same idea draws the same size in both frames');
+  assert.ok(crowded.get('8').scale > crowded.get('7').scale, 'and the bigger thought is still bigger');
+});
+
+// ---------------------------------------------------------------------------
+// 2. the read — the boundary, the streams, and the shape of the SQL
+// ---------------------------------------------------------------------------
+
+await test('size is the SUM of every stream-1 payout under an idea', async () => {
+  const c = ledgerClient([paid(7, 500, 5), paid(7, 501, 3), paid(7, 502, 1)]);
+  const size = await ideaSizeLib.ideaSize('7', { client: c });
+  assert.equal(size.credits, 9, 'the direct payout and every decayed one below it');
+  assert.equal(size.payments, 3, 'and how many payouts made it up');
+  assert.equal(size.scale, ideaSizeLib.compressIdeaSize(9), 'with the drawn magnitude applied once, at the read');
+});
+
+await test('THE BOUNDARY: idea 1 does not absorb the payouts of ideas 10 and 100', async () => {
+  // The bug a prefix match without its trailing separator produces. It raises no
+  // error and renders no differently — one ideator is simply paid-looking for
+  // everyone else's work.
+  const c = ledgerClient([paid(1, 500, 5), paid(10, 501, 40), paid(100, 502, 400), paid(1, 503, 2)]);
+  const sizes = await ideaSizeLib.ideaSizes(['1', '10', '100'], { client: c });
+  assert.equal(sizes.get('1').credits, 7, 'idea 1 is worth its own two payouts and nothing else');
+  assert.equal(sizes.get('10').credits, 40);
+  assert.equal(sizes.get('100').credits, 400);
+});
+
+await test('and the SQL that delivers it groups on the SEPARATOR, never a per-idea LIKE', async () => {
+  // The twin above can only prove the arithmetic of a predicate it implements
+  // itself, so the real statement is pinned clause by clause. Rewriting this
+  // read as `reason LIKE 'idea.credit.task_ship:' || id || ':%'` would pass the
+  // test above and reintroduce the boundary the day someone drops the colon.
+  const c = ledgerClient([]);
+  await ideaSizeLib.ideaSizes(['1'], { client: c });
+  const { sql } = c.log[0];
+  assert.match(sql, /split_part\(reason, ':', 2\)/, 'the idea id comes off the separator');
+  assert.match(sql, /GROUP BY/, 'one grouped scan, not one query per idea');
+  assert.ok(sql.includes("reason LIKE '") && sql.includes("%'"),
+    'the stream guard is the writers own constant, not a retyped literal');
+  assert.doesNotMatch(sql, /\|\|\s*':'/, 'no hand-built per-idea key');
+});
+
+// ---------------------------------------------------------------------------
+// 2b. the INDEX — and the drift that would silently un-index the read
+// ---------------------------------------------------------------------------
+
+// A grader panel caught this on the first round of task 1004093: credit_log is
+// the whole-instance, append-only ledger, so an unindexed size read is a
+// sequential scan of every credit event the instance has ever booked, on every
+// view of a builder's idea trail. core_251 adds a partial expression index.
+//
+// The failure mode of a PARTIAL index is the quiet one, which is why it is
+// tested rather than trusted: Postgres uses it only when it can prove the
+// query's WHERE implies the index predicate. If the two strings stop matching —
+// because the reason key changed, or because someone "tidied" the literal back
+// into a bind parameter — nothing errors, nothing renders differently, and the
+// scan simply returns.
+
+const MIGRATION = fs.readFileSync(
+  path.join(ROOT, 'migrations', 'core_251_credit_log_idea_size_index.sql'), 'utf8');
+
+await test('the migration indexes the SAME expression the read groups on', () => {
+  assert.match(MIGRATION, /CREATE INDEX IF NOT EXISTS/, 'additive and idempotent');
+  assert.match(MIGRATION, /ON credit_log \(\(split_part\(reason, ':', 2\)\)\)/,
+    'an index on the grouping EXPRESSION — an index on `reason` alone cannot serve it');
+  // The STATEMENT, not the file — the header explains why CONCURRENTLY is
+  // absent, and a naive scan of the whole file would read its own explanation
+  // as the violation.
+  const statements = MIGRATION.split('\n').filter((l) => !l.trim().startsWith('--')).join('\n');
+  assert.match(statements, /CREATE INDEX/, 'the probe found the statement, so this is not vacuous');
+  assert.doesNotMatch(statements, /CONCURRENTLY/,
+    'the runner wraps each file in a transaction, and CREATE INDEX CONCURRENTLY cannot run inside one');
+});
+
+await test('the index predicate and the query guard are the SAME literal', async () => {
+  // The drift guard. Held against the economy constant on one side and the
+  // statement the read actually issues on the other, so neither can move alone.
+  const unescape = (s) => s.replace(/\\([\\%_])/g, (m, ch) => ch);
+  const inMigration = /WHERE reason LIKE '([^']*)%'/.exec(MIGRATION);
+  assert.ok(inMigration, 'the index is partial on the stream-1 prefix');
+  assert.equal(unescape(inMigration[1]), PREFIX,
+    'the migration predicate is the writers own reason prefix');
+
+  const c = ledgerClient([]);
+  await ideaSizeLib.ideaSizes(['1'], { client: c });
+  const inQuery = /WHERE reason LIKE '([^']*)%'/.exec(c.log[0].sql);
+  assert.ok(inQuery, 'and the query spells it as a LITERAL, not a bind parameter');
+  assert.equal(inQuery[1], inMigration[1],
+    'a parameterised predicate cannot be proven to imply the partial index, so the index would never be chosen');
+});
+
+await test('the inlined prefix is fenced, and its LIKE wildcard is ESCAPED', async () => {
+  // The literal is module-owned and never touches a request, but inlining any
+  // string into SQL earns a guard: the module refuses to build the fragment from
+  // anything that is not plain prefix characters.
+  assert.match(PREFIX, /^[a-z0-9_.]+:$/i, 'the constant this file inlines is a plain literal');
+  assert.doesNotMatch(PREFIX, /['\\%]/, 'no quote and no escape character to break out of the literal');
+
+  // AND `task_ship` carries an underscore, which in LIKE matches ANY single
+  // character — so an unescaped predicate also matches `idea.credit.taskXship:`.
+  // No such key exists, which is exactly why it would never be noticed.
+  assert.match(PREFIX, /_/, 'the prefix really does contain a wildcard, so this is not vacuous');
+  const c = ledgerClient([]);
+  await ideaSizeLib.ideaSizes(['1'], { client: c });
+  assert.ok(c.log[0].sql.includes('task\\_ship'), 'the query escapes it');
+  assert.ok(MIGRATION.includes('task\\_ship'), 'and the index predicate escapes it identically');
+});
+
+await test('a whole PAGE of ideas costs ONE query, not one per idea', async () => {
+  const c = ledgerClient([]);
+  await ideaSizeLib.ideaSizes(['1', '2', '3', '4', '5', '6', '7', '8'], { client: c });
+  assert.equal(c.log.length, 1, 'the round-trip count is independent of how many ideas the page carries');
+});
+
+await test('the OTHER ideator streams are not size — they pay for the thought, not its work', async () => {
+  const c = ledgerClient([
+    paid(7, 500, 5),
+    { reason: `${credits.IDEA_STREAM_REASON_PREFIXES.full_pass}7`, delta: 5 },
+    { reason: `${credits.IDEA_STREAM_REASON_PREFIXES.governance_pass}7`, delta: 100 },
+    { reason: 'idea_promotion_bonus', delta: 12 },
+    { reason: 'task.shipped', delta: 30 },
+  ]);
+  const size = await ideaSizeLib.ideaSize('7', { client: c });
+  assert.equal(size.credits, 5, 'only stream 1 — a Full Idea that caused nothing must not draw large');
+  assert.equal(size.payments, 1);
+});
+
+await test('every idea asked for comes back, at zero when nothing has been paid', async () => {
+  const sizes = await ideaSizeLib.ideaSizes(['7', '8'], { client: ledgerClient([paid(7, 500, 5)]) });
+  assert.equal(sizes.get('8').credits, 0,
+    '"this thought has earned nothing yet" is an answer a renderer must be able to draw');
+  assert.equal(sizes.get('8').paid, 0);
+  assert.ok(sizes.has('8'), 'absent and zero are different answers; the read never returns a gap');
+});
+
+await test('an id that is not a positive integer never reaches the database', async () => {
+  const c = ledgerClient([]);
+  const sizes = await ideaSizeLib.ideaSizes(['7', "1; DROP TABLE credit_log", '-3', null, '007x'], { client: c });
+  assert.deepEqual([...sizes.keys()], ['7'], 'only the legitimate id survives');
+  assert.doesNotMatch(JSON.stringify(c.log[0].params), /DROP TABLE/);
+});
+
+await test('asking about nothing asks the database nothing', async () => {
+  const c = ledgerClient([]);
+  assert.equal((await ideaSizeLib.ideaSizes([], { client: c })).size, 0);
+  assert.equal((await ideaSizeLib.ideaSize('nonsense', { client: c })).credits, 0);
+  assert.equal(c.log.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// 3. the port
+// ---------------------------------------------------------------------------
+
+await test('size rides the `reward` port, so ideas never reads credit_log itself', async () => {
+  for (const name of ['ideaSize', 'ideaSizes', 'compressIdeaSize']) {
+    assert.equal(typeof reward[name], 'function', `${name} is on the port surface`);
+  }
+  assert.equal(reward.IDEA_SIZE_SCALE_REF, ideaSizeLib.IDEA_SIZE_SCALE_REF,
+    'and the reference constant, so a drawing uses the same curve the read applied');
+  const c = ledgerClient([paid(7, 500, 5)]);
+  assert.equal((await reward.ideaSize('7', { client: c })).credits, 5, 'the port delegates to the real read');
+});
+
+// ---------------------------------------------------------------------------
+// 4. SIZE NEVER FALLS — tested where the invariant actually lives
+// ---------------------------------------------------------------------------
+
+// The module header claims size cannot fall, and the read applies no clamp to
+// make that true — deliberately, because a clamp would hide the anomaly rather
+// than prevent it. The property lives in the WRITERS: both stream-1 payout paths
+// drop a payment whose rounded delta is <= 0, and ADR 0313 claws nothing back.
+// So it is driven here, through the real credits.js, rather than asserted in a
+// comment nothing runs.
+
+function writerClient(lineage = {}) {
+  const booked = [];
+  return {
+    booked,
+    async query(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)) {
+        booked.push({ builder_id: params[0], task_id: params[1], delta: params[2], reason: params[3] });
+        return { rowCount: 1, rows: [] };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+let ancestorsFixture = [];
+// Descendants keyed by root task id. Registered on the SAME provider object as
+// the walk the payout uses, because a port is single-provider — §5c varies this
+// fixture rather than re-registering.
+let descendantsFixture = new Map();
+api.registerProvider('ideas.descent', {
+  ancestorsOfTask: async () => ancestorsFixture,
+  // Deliberately shaped like the REAL walk: rows off ideas_task_descent, which
+  // is an edge table with no join to `tasks`, so they carry id/depth/relation
+  // and NO STATUS. A stub that helpfully added one would hide the exact bug the
+  // hydration in walkDescentForIdeas exists to prevent.
+  descendantsOfTask: async (taskId) => (descendantsFixture.get(String(taskId)) || []),
+});
+
+await test('no stream-1 writer ever books a non-positive delta — the source of "size never falls"', async () => {
+  // A descent deep enough that the decayed share rounds away entirely at the
+  // bottom. Those hops must contribute NOTHING, never a zero or negative row —
+  // a zero row is harmless arithmetic and a lie about how many payouts an idea
+  // received; a negative one would make a star shrink.
+  const lineage = {};
+  ancestorsFixture = [];
+  for (let d = 1; d <= 8; d += 1) {
+    const taskId = 600 + d;
+    ancestorsFixture.push({ id: taskId, depth: d, relation: 'split' });
+    lineage[String(taskId)] = {
+      task_id: String(taskId), idea_id: 70 + d, captured_by: 3,
+      grade: 'quick', completeness: null, developed_by: null,
+    };
+  }
+  const c = writerClient(lineage);
+  await credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: rewardPolicy({}) });
+  assert.ok(c.booked.length > 0, 'the near hops did pay, so this is not vacuous');
+  for (const row of c.booked) {
+    assert.ok(String(row.reason).startsWith(PREFIX), 'every row booked here is a stream-1 row');
+    assert.ok(row.delta > 0, `a payout of ${row.delta} was booked under ${row.reason}`);
+  }
+  // And the rounded-away hops are genuinely absent rather than booked at zero.
+  const deepest = c.booked.map((r) => Number(String(r.reason).split(':')[1])).sort((a, b) => b - a)[0];
+  assert.ok(deepest < 78, 'the hops whose share no longer rounds to a credit book nothing at all');
+});
+
+await test('a size read over a real writer run is the sum of what was actually booked', async () => {
+  // The two halves meeting: what the writers put in the ledger is what the read
+  // adds up. Nothing between them is hand-built.
+  const c = writerClient({
+    601: { task_id: '601', idea_id: 71, captured_by: 3, grade: 'quick', completeness: null, developed_by: null },
+    602: { task_id: '602', idea_id: 71, captured_by: 3, grade: 'quick', completeness: null, developed_by: null },
+  });
+  ancestorsFixture = [{ id: 601, depth: 1, relation: 'split' }];
+  await credits.awardIdeaDescentShipCredit(c, { taskId: 900, config: rewardPolicy({}) });
+  ancestorsFixture = [{ id: 602, depth: 1, relation: 'split' }];
+  await credits.awardIdeaDescentShipCredit(c, { taskId: 901, config: rewardPolicy({}) });
+  const expected = c.booked.reduce((n, r) => n + r.delta, 0);
+  assert.ok(expected > 0);
+  const size = await ideaSizeLib.ideaSize('71', { client: ledgerClient(c.booked) });
+  assert.equal(size.credits, expected, 'the ledger is the only source of the figure');
+  assert.equal(size.payments, c.booked.length);
+});
+
+// ---------------------------------------------------------------------------
+// 5. the trail attach — and the branch where the port is not there
+// ---------------------------------------------------------------------------
+
+await test('with the reward port absent, size is NULL — which is not zero', async () => {
+  // Run before the port is registered: a port is single-provider and cannot be
+  // unregistered, so this is the only honest place for the absent branch.
+  assert.equal(api.hasProvider('reward'), false, 'nothing has registered it yet');
+  const ideas = [{ id: '7' }, { id: '8' }];
+  await trailSize.attachSizeToTrail(ideas);
+  assert.equal(ideas[0].size, null, '"we could not ask the ledger" must not render as "you earned nothing"');
+  assert.equal(ideas[1].size, null);
+});
+
+api.registerProvider('reward', reward);
+
+await test('the trail attaches each idea its OWN size, in one read for the page', async () => {
+  const c = ledgerClient([paid(7, 500, 5), paid(7, 501, 2), paid(9, 502, 40)]);
+  const ideas = [{ id: '7' }, { id: '8' }, { id: '9' }];
+  await trailSize.attachSizeToTrail(ideas, { client: c });
+  assert.equal(ideas[0].size.credits, 7);
+  assert.equal(ideas[1].size.credits, 0);
+  assert.equal(ideas[1].size.historical, false, 'an idea with no descent has nothing estimated');
+  assert.equal(ideas[2].size.credits, 40);
+  // The property is that the round trips do NOT scale with the page, not that
+  // there is exactly one of them: BV2.R18 added a second read (the grades that
+  // price the historical half), and pinning the literal 1 would have made a
+  // correct change look like a regression. A page of twelve must cost what a
+  // page of three costs — that is the claim, and it is invisible in review.
+  const small = c.log.length;
+  const big = ledgerClient([paid(7, 500, 5)]);
+  const many = [];
+  for (let i = 0; i < 12; i += 1) many.push({ id: String(20 + i) });
+  await trailSize.attachSizeToTrail(many, { client: big });
+  assert.equal(big.log.length, small, 'a page of twelve costs what a page of three costs');
+});
+
+await test('a MERGED idea keeps its own size — the descent it shows is inherited, the money is not', async () => {
+  // trail-descent.js deliberately hands a merged idea the TARGET's tasks, so the
+  // easy mistake is to hand it the target's payouts too. Stream 1 books against
+  // the idea whose lineage row named the shipping task; crediting both would
+  // count one piece of work twice on a single page.
+  const c = ledgerClient([paid(901, 500, 40)]);
+  const ideas = [
+    { id: '903', status: 'merged', merged_into_idea_id: '901' },
+    { id: '901', status: 'promoted' },
+  ];
+  await trailSize.attachSizeToTrail(ideas, { client: c });
+  assert.equal(ideas[0].size.credits, 0, 'the merged thought earned nothing of its own');
+  assert.equal(ideas[1].size.credits, 40, 'the target keeps what its work was paid');
+  assert.doesNotMatch(JSON.stringify(c.log[0].params), /"901"[\s\S]*"901"/,
+    'and the merge target is never asked for twice');
+});
+
+// ---------------------------------------------------------------------------
+// 5b. THE HISTORICAL HALF — task 1004097 / BV2.R18, spec decision 17
+// ---------------------------------------------------------------------------
+
+// A pre-existing idea's ledger figure is PARTIAL, not absent: the direct payout
+// has existed since ADR 0172, the DESCENT payout only since task 1004088. So the
+// backfill is the gap, it is computed at read time, and NO credits are booked.
+// The failure modes are all quiet ones:
+//
+//   * DOUBLE-COUNTING. Estimating for a hop the ledger already paid makes every
+//     long-lived idea read roughly twice its real size, with nothing to show it.
+//   * PAYING FOR WORK THAT HAS NOT HAPPENED. Estimating for a task that has not
+//     shipped credits a payout that no ship triggered — and makes size FALL when
+//     that task is later abandoned, breaking BV2.R12's headline invariant.
+//   * AN UNMARKED TOTAL. The spec calls this the quiet lie: a number that is
+//     partly an estimate, rendered as though it were money that moved.
+
+await test('the backfill estimates ONLY the hops the ledger never paid for', async () => {
+  // Depth 0 was paid (5c, really banked). The two hops below it shipped before
+  // the descent payout existed, so they were never paid and are estimated at the
+  // decayed rate: quick factor 0.6 × base 5 × 0.5 = 2 at depth 1, × 0.25 = 1 at
+  // depth 2. Paid 5 + estimated 3 = 8.
+  const c = ledgerClient([paid(7, 500, 5)]);
+  const descentByIdea = new Map([['7', [
+    { task_id: '500', depth: 0, status: 'shipped' },
+    { task_id: '501', depth: 1, status: 'shipped' },
+    { task_id: '502', depth: 2, status: 'shipped' },
+  ]]]);
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c, descentByIdea })).get('7');
+  assert.equal(size.paid, 5, 'money that moved is read off the ledger, never re-derived');
+  assert.equal(size.estimated, 3, 'and only the unpaid hops are priced');
+  assert.equal(size.credits, 8, 'size is the two together');
+  assert.equal(size.historical, true, 'and it says so');
+});
+
+await test('a hop the ledger DID pay is never estimated on top of', async () => {
+  // The double-counting case. Every task in the descent has a real payment, so
+  // there is nothing to estimate and the idea is not historical at all.
+  const c = ledgerClient([paid(7, 500, 5), paid(7, 501, 2), paid(7, 502, 1)]);
+  const descentByIdea = new Map([['7', [
+    { task_id: '500', depth: 0, status: 'shipped' },
+    { task_id: '501', depth: 1, status: 'shipped' },
+    { task_id: '502', depth: 2, status: 'shipped' },
+  ]]]);
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c, descentByIdea })).get('7');
+  assert.equal(size.paid, 8);
+  assert.equal(size.estimated, 0, 'a paid hop contributes its PAYMENT, not a second estimate');
+  assert.equal(size.credits, 8, 'not 16');
+  assert.equal(size.historical, false, 'an idea whose descent was fully paid is not historical');
+});
+
+await test('an UNSHIPPED descendant is worth nothing — a payout happens at ship', async () => {
+  // Estimating for work that has not shipped would credit a payout nothing
+  // triggered, and would make size FALL the day that task is abandoned.
+  const c = ledgerClient([]);
+  const before = new Map([['7', [
+    { task_id: '500', depth: 0, status: 'shipped' },
+    { task_id: '501', depth: 1, status: 'ready' },
+    { task_id: '502', depth: 1, status: 'abandoned' },
+  ]]]);
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c, descentByIdea: before })).get('7');
+  assert.equal(size.estimated, 3, 'only the shipped depth-0 task is priced (5 × 0.6)');
+
+  // And when the ready one ships, size RISES. It must never have been counted
+  // early, or this would be a fall.
+  const after = new Map([['7', [
+    { task_id: '500', depth: 0, status: 'shipped' },
+    { task_id: '501', depth: 1, status: 'shipped' },
+    { task_id: '502', depth: 1, status: 'abandoned' },
+  ]]]);
+  const later = (await ideaSizeLib.ideaSizes(['7'], { client: ledgerClient([]), descentByIdea: after })).get('7');
+  assert.ok(later.credits > size.credits, 'a ship raises size; nothing here can lower it');
+});
+
+await test('the backfill BOOKS NOTHING — it is a read, and the ledger is untouched', async () => {
+  const c = ledgerClient([]);
+  const descentByIdea = new Map([['7', [{ task_id: '500', depth: 0, status: 'shipped' }]]]);
+  await ideaSizeLib.ideaSizes(['7'], { client: c, descentByIdea });
+  for (const q of c.log) {
+    assert.doesNotMatch(q.sql, /INSERT|UPDATE|DELETE/i,
+      'no credits are paid retroactively — the owner declined that, and a write here would also forge stream-1 idempotency keys');
+  }
+});
+
+await test('the estimate uses the SAME arithmetic the real payout uses', async () => {
+  // Not a second copy. A full idea at 100% completeness is worth the full base
+  // at depth 0 — which is what ideaGradeFactor says and what the writer applies.
+  const c = ledgerClient([]);
+  c.query = async (sql, params) => {
+    if (/FROM idea_inbox/i.test(sql)) return { rows: [{ id: 7, grade: 'full', completeness: 100 }] };
+    return { rows: [] };
+  };
+  const descentByIdea = new Map([['7', [{ task_id: '500', depth: 0, status: 'shipped' }]]]);
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c, descentByIdea })).get('7');
+  assert.equal(size.estimated, credits.IDEA_TASK_SHIP_BASE,
+    'a 100%-complete Full Idea earns the full base at depth 0, exactly as the writer pays it');
+  assert.equal(credits.ideaGradeFactor('full', 100), 1, 'and the factor is credits.js own, not a copy');
+});
+
+// ---------------------------------------------------------------------------
+// 5c. the WALK FALLBACK — for a caller with no descent in hand
+// ---------------------------------------------------------------------------
+
+// The trail passes its own already-walked descent, so this path is for a
+// single-idea panel. It is a real branch with a real trap in it, so it is driven
+// rather than assumed.
+
+// A client that answers the three shapes this path issues: the ledger read, the
+// lineage roots, and the task-status hydration.
+function panelClient(ledgerRows, { roots = [], statuses = {}, grade = null } = {}) {
+  const base = ledgerClient(ledgerRows);
+  const log = base.log;
+  return {
+    log,
+    async query(sql, params) {
+      if (/FROM credit_log/i.test(sql)) return base.query(sql, params);
+      log.push({ sql, params });
+      if (/FROM ideas_task_lineage/i.test(sql)) return { rows: roots };
+      if (/FROM idea_inbox/i.test(sql)) {
+        return { rows: grade ? [grade] : [] };
+      }
+      if (/FROM tasks/i.test(sql)) {
+        return { rows: (params[0] || []).map((id) => ({ id, status: statuses[String(id)] ?? null })).filter((r) => r.status != null) };
+      }
+      return { rows: [] };
+    },
+  };
+}
+
+await test('with no map, the walk is done through the PORT — never a second copy of it', async () => {
+  descendantsFixture = new Map([['500', [{ id: 501, from_id: 500, relation: 'split', depth: 1 }]]]);
+  const c = panelClient([paid(7, 500, 5)], {
+    roots: [{ idea_id: 7, task_id: 500, status: 'shipped' }],
+    statuses: { 501: 'shipped' },
+  });
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c })).get('7');
+  assert.equal(size.paid, 5, 'the direct hop was paid');
+  assert.equal(size.estimated, 2, 'and the hop below it is priced from the walk');
+  assert.equal(size.historical, true);
+  descendantsFixture = new Map();
+});
+
+await test('THE WALK RETURNS NO STATUS, so the fallback hydrates it — or it prices nothing', async () => {
+  // The trap this path was written around. ideas_task_descent is an EDGE table
+  // with no join to `tasks`, so the walk's rows carry no status at all. Read
+  // naively, every descendant fails the shipped test, the backfill silently
+  // prices nothing, and it looks exactly like an idea that simply has no
+  // descent. The hydration query is what makes the difference, so its absence
+  // is what this asserts against: a descendant the tasks read says is SHIPPED
+  // must be priced, and one it says is READY must not.
+  descendantsFixture = new Map([['500', [
+    { id: 501, from_id: 500, relation: 'split', depth: 1 },
+    { id: 502, from_id: 500, relation: 'split', depth: 1 },
+  ]]]);
+  const c = panelClient([], {
+    roots: [{ idea_id: 7, task_id: 500, status: 'ready' }],
+    statuses: { 501: 'shipped', 502: 'ready' },
+  });
+  const size = (await ideaSizeLib.ideaSizes(['7'], { client: c })).get('7');
+  assert.ok(c.log.some((q) => /FROM tasks/i.test(q.sql)), 'the statuses are fetched, not read off the walk');
+  assert.equal(size.estimated, 2, 'only the shipped descendant is priced — the root is not shipped, nor is 502');
+  descendantsFixture = new Map();
+});
+
+// ---------------------------------------------------------------------------
+// 6. the WHOLE PATH — the real read into the real page
+// ---------------------------------------------------------------------------
+
+const renderTrail = async (trail) => {
+  const p = bootProfilePage({ trail });
+  await settle(); await settle(); await settle();
+  const html = p.htmlFor('activity-ideas');
+  assert.ok(html, 'the idea trail rendered');
+  return html;
+};
+
+await test('WHOLE PATH: the real read feeds the real page, and it prints the TRUE figure', async () => {
+  // Nothing hand-built between the ledger and the HTML: the fixture is credit_log
+  // rows, the read is the real one, and the page is the real profile renderer.
+  const c = ledgerClient([paid(901, 5001, 5), paid(901, 5002, 2), paid(901, 5003, 1)]);
+  const trail = await trailSize.attachSizeToTrail([
+    {
+      id: '901', title: 'A shared changelog', status: 'promoted', captured_at: '2026-08-01T00:00:00Z',
+      lineage_tasks: [{ task_id: '5001', origin: 'promote', title: 'The first task', status: 'shipped' }],
+      descent_tasks: [],
+    },
+  ], { client: c });
+
+  const html = await renderTrail(trail);
+  assert.ok(html.includes('Earned 8 credits so far'),
+    'the page prints the summed ledger figure, not the compressed magnitude');
+  assert.ok(!/Earned 0\.\d/.test(html), 'the drawn scale never reaches the panel');
+});
+
+await test('RENDERED: an idea with a size but NO descent still shows what it earned', async () => {
+  // The failure mode of hanging this off the descent block: an idea promoted
+  // straight into one task that shipped has a size and no descent at all, and
+  // its ideator would be shown nothing.
+  const c = ledgerClient([paid(902, 5001, 5)]);
+  const trail = await trailSize.attachSizeToTrail([
+    {
+      id: '902', title: 'A small thought', status: 'promoted', captured_at: '2026-08-01T00:00:00Z',
+      lineage_tasks: [{ task_id: '5001', origin: 'promote', title: 'The only task', status: 'shipped' }],
+      descent_tasks: [],
+    },
+  ], { client: c });
+  const html = await renderTrail(trail);
+  assert.ok(html.includes('Earned 5 credits so far'));
+  assert.ok(!html.includes('Then caused'), 'and it genuinely has no descent to have hung it from');
+});
+
+await test('RENDERED: an idea that has earned nothing says nothing, and a null size says nothing either', async () => {
+  // Two different reasons to print no figure, and neither may print a zero: "you
+  // have earned nothing yet" is the ledger's honest answer and belongs in the
+  // empty state the outcome line already gives, and a null means the figure was
+  // never established.
+  const html = await renderTrail([
+    { id: '904', title: 'Still thinking', status: 'open', captured_at: '2026-05-01T00:00:00Z', lineage_tasks: [], descent_tasks: [], size: { credits: 0, payments: 0, scale: 0 } },
+    { id: '905', title: 'Unknowable', status: 'open', captured_at: '2026-05-01T00:00:00Z', lineage_tasks: [], descent_tasks: [], size: null },
+  ]);
+  assert.doesNotMatch(html, /Earned 0 credits/, 'zero is not a thing to boast about on a ledger row');
+  assert.doesNotMatch(html, /Earned .* credits so far[\s\S]*Earned/, 'and neither row printed a figure');
+});
+
+await test('WHOLE PATH: a HISTORICAL idea says on the page which kind of number it is', async () => {
+  // The done-when of BV2.R18: anywhere size is shown makes clear which kind of
+  // number it is. Nothing hand-built between the ledger and the HTML — the
+  // fixture is credit_log rows plus a real descent, the read is the real one,
+  // and the page is the real profile renderer.
+  const c = ledgerClient([paid(907, 5001, 5)]);
+  const trail = await trailSize.attachSizeToTrail([
+    {
+      id: '907', title: 'An old thought', status: 'promoted', captured_at: '2026-02-01T00:00:00Z',
+      lineage_tasks: [{ task_id: '5001', origin: 'promote', title: 'The first task', status: 'shipped' }],
+      descent_tasks: [
+        { task_id: '5002', depth: 1, relation: 'split', origin_task_id: '5001', title: 'Split out', status: 'shipped', version_id: 'BONGOS-V2', kind: 'feature' },
+      ],
+    },
+  ], { client: c });
+
+  assert.equal(trail[0].size.paid, 5, 'the direct hop really was paid');
+  assert.equal(trail[0].size.estimated, 2, 'the hop below it never was');
+  assert.equal(trail[0].size.historical, true);
+
+  const html = await renderTrail(trail);
+  assert.ok(html.includes('Worth 7 credits'), 'the total is shown');
+  assert.match(html, /2 of it estimated/, 'and the part that is NOT money that moved is named');
+  assert.ok(!html.includes('Earned 7 credits so far'),
+    'it must not be phrased as earnings — that is the quiet lie the spec names');
+});
+
+await test('RENDERED: a fully-paid idea is NOT marked historical', async () => {
+  // The opposite direction, so the marker is not simply always on.
+  const html = await renderTrail([
+    {
+      id: '908', title: 'A recent thought', status: 'promoted', captured_at: '2026-09-01T00:00:00Z',
+      lineage_tasks: [], descent_tasks: [],
+      size: { credits: 5, paid: 5, estimated: 0, payments: 1, scale: 0.3, historical: false },
+    },
+  ]);
+  assert.ok(html.includes('Earned 5 credits so far'), 'plain earnings wording');
+  assert.doesNotMatch(html, /estimated/, 'and no marker where none is due');
+});
+
+await test('RENDERED: an UNKNOWN historical state claims neither', async () => {
+  // historical: null — the estimate could not be established. It must not print
+  // as "estimated" (a claim) nor be silently folded in as though it were all
+  // money that moved, so it falls back to the plain figure and no marker.
+  const html = await renderTrail([
+    {
+      id: '909', title: 'Unknowable', status: 'promoted', captured_at: '2026-09-01T00:00:00Z',
+      lineage_tasks: [], descent_tasks: [],
+      size: { credits: 5, paid: 5, estimated: null, payments: 1, scale: 0.3, historical: null },
+    },
+  ]);
+  assert.doesNotMatch(html, /estimated/, 'unknown is not a claim that anything was estimated');
+  assert.ok(html.includes('5 credit'), 'but what IS known still shows');
+});
+
+await test('RENDERED: the figure is a number, so a hostile size cannot reach the page as markup', async () => {
+  const html = await renderTrail([
+    {
+      id: '906', title: 'A thought', status: 'promoted', captured_at: '2026-05-01T00:00:00Z',
+      lineage_tasks: [], descent_tasks: [],
+      size: { credits: '<script>alert(1)</script>', payments: 1, scale: 0 },
+    },
+  ]);
+  assert.doesNotMatch(html, /<script>/, 'a non-numeric credits value is refused outright, not escaped and printed');
+  assert.doesNotMatch(html, /Earned/, 'the row simply carries no figure');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);