@bongos/core 1.19.921 → 1.19.923

package/modules/economy/idea-brightness.js

@@ -0,0 +1,212 @@
+'use strict';
+
+// modules/economy/idea-brightness.js — BRIGHTNESS: the live share of an idea's
+// descent (task 1004099 / BV2.R16, goal 1000095; spec
+// docs/specs/bongos-v2-ideator-surface.md decisions 4 and 20; ADR 0321, under
+// ADR 0313 + 0319).
+//
+// WHAT BRIGHTNESS IS. Size is an idea's total ideator payout from its descent and
+// NEVER falls (./idea-size.js). Brightness is how much of that payout is still
+// alive: the same sum, restricted to the descent tasks the project has not since
+// confirmed as removed, over the whole. Two channels, two facts — and the pair is
+// the entire point. A thought that caused a version the project later tore out
+// draws LARGE AND DARK, which is visibly different from a thought that never
+// caused anything and draws small and dark. One number could not say that.
+//
+// GRADED, NOT BINARY (spec decision 20). A descent of five things with three
+// still alive is partly lit. It goes out only when nothing survives. So this is a
+// share in [0, 1] and not a flag — an idea dims progressively as pieces of its
+// work are removed.
+//
+// WEIGHTED BY PAYOUT, NOT BY COUNT, and that is the decision in this file.
+// Counting tasks would make removing a one-line fix dim a star as much as
+// removing the feature it belongs to. Weighting by what each hop actually earned
+// means brightness falls in proportion to how much of the idea's WORTH died,
+// which is the same quantity size is drawn from — so the two channels are a
+// share of one number rather than two unrelated measurements that happen to sit
+// side by side. It also makes "large and dead" exact: full size, zero brightness.
+//
+// THE BASIS IS PAID + ESTIMATED, the same as size. A historical idea's descent
+// was never paid for (./idea-size-historical.js prices those hops), and if
+// brightness counted only banked credits, removing an estimated hop would dim
+// nothing while the size drawn beside it still counted that hop. The share would
+// then be a fraction of a different number than the one on screen.
+//
+// BRIGHTNESS NEVER CLAWS BACK CREDITS, and nothing here could. This module only
+// READS — no writer, no ledger row, no status change. ADR 0313 settles that
+// `shipped` is terminal and the ledger is never rewritten when the project
+// changes its mind: only the picture changes. Size is computed from credit_log
+// and is untouched by anything in this file.
+//
+// WHAT COUNTS AS REMOVED IS A PERSON'S ANSWER, never a derived one. A ship that
+// deletes an earlier shipped task's files files a QUESTION (the
+// `removal-proposed-on-ship` cascade), someone confirms or dismisses it, and only
+// 'confirmed' reaches this read. Refactors, renames and file moves all look like
+// deletions to a diff, so a derived-only signal would dim the sky continuously —
+// ADR 0313's central finding, and the reason `dismissed` exists at all.
+//
+// MODULE BOUNDARY: the removal facts live in the LIFECYCLE module and are reached
+// through the kernel-mediated `lifecycle.removals` port, never a cross-module
+// require (ADR 0083 rule 1) — the same way ./idea-size.js reaches `ideas.descent`.
+
+const api = require('../../src/module-api');
+const { resolveOptional } = api;
+const { ideaSizes } = require('./idea-size');
+
+// A positive integer id as it arrives off a row or a caller, where it may be a
+// bigint serialised to a string. Never coerced with Number(); the guard
+// ./idea-size.js uses, for the same precision reason.
+function idOf(v) {
+  return /^[1-9]\d*$/.test(String(v)) ? String(v) : null;
+}
+
+// ideaBrightnesses — brightness for MANY ideas, keyed by idea id (string).
+//
+// Returns Map<ideaIdString, {
+//   share       number in [0,1] — the live fraction of the descent's payout,
+//               or null when it could not be established (see below)
+//   live        credits still alive
+//   removed     credits whose work is confirmed gone
+//   credits     the total the two divide (equals size's `credits`)
+//   removedTasks  [{ taskId, credits, proposalTaskId, paths }] — WHAT went out,
+//               so a surface can say why a star dimmed instead of only that it
+//               did
+//   hasWork     false when the idea has earned nothing at all
+//   attributable  false when the removal facts could not be read
+// }>
+//
+// EVERY ID ASKED FOR IS PRESENT. Absent and dark are different answers, and an
+// idea that caused nothing yet is a real state the sky has to draw.
+//
+// AN IDEA THAT EARNED NOTHING IS `share: 1`, `hasWork: false` — LIT, NOT DARK,
+// and this is the sharpest edge in the file. Zero over zero is not zero. A
+// freshly-filed thought has had nothing removed from it; it is a protostar, not a
+// remnant. Returning 0 would light-for-light merge it with the thought whose
+// version was torn out, which is exactly the distinction BV2.R19's proof exists
+// to check. `hasWork` is what lets the five states (BV2.R17) tell the two apart
+// without re-deriving it.
+//
+// WHEN THE REMOVAL FACTS CANNOT BE READ — the lifecycle module is off, or the
+// port is unregistered — `share` is NULL and `attributable` is false, rather than
+// 1. "Nothing was removed" and "we could not look" are different answers and only
+// one of them may be drawn as a plain full-brightness star. Same posture
+// ./idea-size.js takes with `historical: null` when the descent walk is
+// unavailable.
+//
+//   ideaIds        — array of ids (bigint-safe strings or numbers)
+//   client         — optional tx client; falls back to the pool inside the reads
+//   descentByIdea  — the caller's already-walked descent, passed straight through
+//                    to ideaSizes so a page that has one costs no extra walk
+//   sizes          — an already-computed ideaSizes() result, when the caller has
+//                    one. Brightness needs the same per-task figures size does,
+//                    so a surface drawing both should compute sizes once and hand
+//                    them here rather than paying for the whole read twice.
+async function ideaBrightnesses(ideaIds, { client = null, descentByIdea = null, sizes = null } = {}) {
+  const ids = [...new Set((Array.isArray(ideaIds) ? ideaIds : []).map(idOf).filter(Boolean))];
+  const out = new Map();
+  if (ids.length === 0) return out;
+
+  const sized = sizes || await ideaSizes(ids, { client, descentByIdea });
+
+  // The per-task breakdown. `ideaSizes` carries the totals; `byTask` is what
+  // lets a share be taken of them, and it is absent only when the descent could
+  // not be walked at all — in which case there is nothing to attribute against
+  // and the idea reads unattributable below.
+  const perTask = new Map();
+  for (const id of ids) {
+    const s = sized.get(id);
+    perTask.set(id, (s && s.byTask instanceof Map) ? s.byTask : null);
+  }
+
+  // Every descent task across every idea asked for, in ONE port call. A lookup
+  // per idea would be a round trip per star on a page of them.
+  const allTaskIds = new Set();
+  for (const byTask of perTask.values()) {
+    if (!byTask) continue;
+    for (const taskId of byTask.keys()) allTaskIds.add(taskId);
+  }
+
+  const port = resolveOptional && resolveOptional('lifecycle.removals');
+  let confirmed = null;
+  if (port && typeof port.confirmedRemovalsForTasks === 'function' && allTaskIds.size > 0) {
+    confirmed = await port.confirmedRemovalsForTasks([...allTaskIds], { client });
+  } else if (port && typeof port.confirmedRemovalsForTasks === 'function') {
+    // The port is there and there is simply nothing to ask about. That is an
+    // established answer — no removals — not an unreadable one.
+    confirmed = new Map();
+  }
+
+  for (const id of ids) {
+    const s = sized.get(id) || { credits: 0 };
+    const byTask = perTask.get(id);
+    const credits = Number(s.credits) || 0;
+
+    if (!confirmed || !byTask) {
+      out.set(id, {
+        share: null, live: null, removed: null, credits,
+        removedTasks: [], hasWork: credits > 0, attributable: false,
+      });
+      continue;
+    }
+
+    let removed = 0;
+    const removedTasks = [];
+    for (const [taskId, taskCredits] of byTask) {
+      const hit = confirmed.get(taskId);
+      if (!hit) continue;
+      const c = Number(taskCredits) || 0;
+      removed += c;
+      removedTasks.push({
+        taskId,
+        credits: c,
+        proposalTaskId: hit.proposalTaskId,
+        paths: hit.paths,
+      });
+    }
+
+    // The live half comes off the TOTAL minus what died, not off a second sum
+    // over the surviving tasks. The two differ: `credits` includes payouts for
+    // tasks the descent no longer reaches (a re-parented task, a deleted edge),
+    // which ./idea-size.js keeps on purpose so size cannot fall. Summing the
+    // survivors would quietly drop those and make a re-parenting dim a star.
+    const live = credits - removed;
+    // Clamped at the bottom only, and never at the top. `removed` is a subset of
+    // the same figures `credits` was built from so it cannot exceed it — but if
+    // it ever did, a negative brightness is a rendering bug where a zero is a
+    // legible "nothing survives". The anomaly is still visible in `live` and
+    // `removed`, which are reported unclamped.
+    const share = credits > 0 ? Math.max(0, live) / credits : 1;
+
+    out.set(id, {
+      share,
+      live,
+      removed,
+      credits,
+      // Largest loss first: a surface explaining why a star dimmed wants the
+      // piece that mattered, not the first one the descent happened to yield.
+      removedTasks: removedTasks.sort((a, b) => b.credits - a.credits),
+      hasWork: credits > 0,
+      attributable: true,
+    });
+  }
+  return out;
+}
+
+// ideaBrightness — the same answer for one idea. A thin wrapper on purpose: two
+// implementations of "how lit is this thought" is two answers, and this is the
+// shape a single-idea panel wants. Mirrors ./idea-size.js's ideaSize.
+async function ideaBrightness(ideaId, opts = {}) {
+  const key = idOf(ideaId);
+  const unknown = {
+    share: null, live: null, removed: null, credits: 0,
+    removedTasks: [], hasWork: false, attributable: false,
+  };
+  if (!key) return unknown;
+  const all = await ideaBrightnesses([key], opts);
+  return all.get(key) || unknown;
+}
+
+module.exports = {
+  ideaBrightness,
+  ideaBrightnesses,
+};

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

@@ -56,7 +56,11 @@ const {
 //   decay       — the resolved per-instance dial (reward-policy ideaDescentDecay)
 //   paidByTask  — Map<taskIdString, creditsPaid> from credit_log, per task
 //
-// Returns { paid, estimated, payments, estimatedPayments }.
+// Returns { paid, estimated, payments, estimatedPayments, byTask }, where
+// `byTask` is Map<taskIdString, credits> — the per-hop breakdown brightness
+// weights a descent by (task 1004099 / BV2.R16). The early return on an
+// unusable decay yields an EMPTY map rather than no map, so a caller never has
+// to test for its absence.
 //
 // ONLY A SHIPPED TASK COUNTS. The payout fires at ship, so a ready or abandoned
 // descendant has earned its origin nothing and estimating for it would credit
@@ -75,7 +79,19 @@ const {
 // what the same descent would have been paid hop by hop, which is the whole
 // thing this function exists to reproduce.
 function priceDescentForIdea({ tasks, grade, completeness, decay, paidByTask } = {}) {
-  const out = { paid: 0, estimated: 0, payments: 0, estimatedPayments: 0 };
+  // `byTask` — the same arithmetic, kept per task instead of only summed
+  // (task 1004099 / BV2.R16). Brightness is the LIVE SHARE of a size, so it has
+  // to weight each descent task by what that task contributed, and the totals
+  // alone cannot be taken apart again afterwards. Added here rather than
+  // recomputed in brightness because a second copy of this loop is a second
+  // answer to "what is this hop worth", and the two would drift the first time
+  // a decay dial or a grade factor moved.
+  //
+  // Map<taskIdString, credits>, carrying BOTH kinds — a paid hop at its ledger
+  // figure and an estimated hop at its priced one. Brightness must use the same
+  // basis as size or the share would be a fraction of a different number than
+  // the one drawn beside it.
+  const out = { paid: 0, estimated: 0, payments: 0, estimatedPayments: 0, byTask: new Map() };
   const list = Array.isArray(tasks) ? tasks : [];
   const paidMap = paidByTask instanceof Map ? paidByTask : new Map();
 
@@ -98,8 +114,10 @@ function priceDescentForIdea({ tasks, grade, completeness, decay, paidByTask } =
     seen.add(key);
 
     if (paidMap.has(key)) {
-      out.paid += Number(paidMap.get(key)) || 0;
+      const banked = Number(paidMap.get(key)) || 0;
+      out.paid += banked;
       out.payments += 1;
+      out.byTask.set(key, banked);
       continue;
     }
 
@@ -113,6 +131,7 @@ function priceDescentForIdea({ tasks, grade, completeness, decay, paidByTask } =
     if (delta <= 0) continue;
     out.estimated += delta;
     out.estimatedPayments += 1;
+    out.byTask.set(key, delta);
   }
   return out;
 }

package/modules/economy/idea-size.js

@@ -152,7 +152,9 @@ function idOf(v) {
 // row is stream 2 — the thought, not the work it caused.
 //
 // Returns Map<ideaIdString, { credits, paid, estimated, payments, scale,
-// historical }>. Every id asked for is present, at zero when it has been paid
+// historical, byTask }>, where `byTask` is Map<taskIdString, credits> summing to
+// `credits` — the per-hop breakdown brightness (./idea-brightness.js, BV2.R16)
+// takes its live share of. Every id asked for is present, at zero when it has been paid
 // nothing: absent and zero are different answers to a renderer, and an idea that
 // caused nothing yet is a real state the surface has to draw, not a gap.
 //
@@ -184,7 +186,10 @@ async function ideaSizes(ideaIds, { client = null, descentByIdea = null } = {})
   const ids = [...new Set((Array.isArray(ideaIds) ? ideaIds : []).map(idOf).filter(Boolean))];
   const out = new Map();
   for (const id of ids) {
-    out.set(id, { credits: 0, paid: 0, estimated: 0, payments: 0, scale: 0, historical: false });
+    // `byTask` empty rather than absent: an idea with no payouts has a real,
+    // established breakdown (nothing), and a caller should not have to tell
+    // that apart from a field that was never filled in.
+    out.set(id, { credits: 0, paid: 0, estimated: 0, payments: 0, scale: 0, historical: false, byTask: new Map() });
   }
   if (ids.length === 0) return out;
 
@@ -235,6 +240,11 @@ async function ideaSizes(ideaIds, { client = null, descentByIdea = null } = {})
       out.set(id, {
         credits: acc.total, paid: acc.total, estimated: null,
         payments: acc.payments, scale: compressIdeaSize(acc.total), historical: null,
+        // The ledger's own per-task figures are still true even with no descent
+        // in hand, and they sum to `credits` here because `credits` IS the
+        // ledger total on this branch. Brightness can therefore still take a
+        // share; it simply cannot see hops that were never paid for.
+        byTask: acc.byTask,
       });
       continue;
     }
@@ -251,6 +261,22 @@ async function ideaSizes(ideaIds, { client = null, descentByIdea = null } = {})
     // edge) is still money this idea was paid, and dropping it would make size
     // fall.
     const credits = acc.total + priced.estimated;
+    // THE PER-TASK BREAKDOWN, for brightness (task 1004099 / BV2.R16), and it
+    // has to SUM TO `credits` or the share taken of it is a fraction of the
+    // wrong number. Two sources, in this order:
+    //
+    //   • `priced.byTask` — every hop the descent reaches, at its ledger figure
+    //     where one was paid and at its priced figure where it was estimated.
+    //   • then any ledger payment for a task the descent NO LONGER REACHES — a
+    //     re-parented task, a deleted edge. Those are in `acc.total` (kept there
+    //     on purpose, a few lines up, so size cannot fall), so leaving them out
+    //     here would make the parts sum to less than the whole and quietly
+    //     overstate brightness. `priced.byTask` wins on a collision because a
+    //     paid hop carries the same banked figure in both.
+    const byTask = new Map(priced.byTask);
+    for (const [taskId, paid] of acc.byTask) {
+      if (!byTask.has(taskId)) byTask.set(taskId, paid);
+    }
     out.set(id, {
       credits,
       paid: acc.total,
@@ -258,6 +284,7 @@ async function ideaSizes(ideaIds, { client = null, descentByIdea = null } = {})
       payments: acc.payments + priced.estimatedPayments,
       scale: compressIdeaSize(credits),
       historical: priced.estimated > 0,
+      byTask,
     });
   }
   return out;
@@ -367,7 +394,7 @@ async function walkDescentForIdeas(ids, { client }) {
 // shape a single-idea panel wants.
 async function ideaSize(ideaId, opts = {}) {
   const key = idOf(ideaId);
-  const zero = { credits: 0, payments: 0, scale: 0 };
+  const zero = { credits: 0, payments: 0, scale: 0, byTask: new Map() };
   if (!key) return zero;
   const sizes = await ideaSizes([key], opts);
   return sizes.get(key) || zero;

package/modules/economy/reward.js

@@ -21,6 +21,7 @@ const cost = require('./cost');
 const streak = require('./streak');
 const ideaSizeLib = require('./idea-size');
 const ideaSizeHistorical = require('./idea-size-historical');
+const ideaBrightnessLib = require('./idea-brightness');
 
 module.exports = {
   // credit allocation — transaction-participant: caller passes its tx `client`
@@ -110,6 +111,16 @@ module.exports = {
   // projection and quietly drops a field the pricing needs.
   descentRowsFromTrail: (...a) => ideaSizeHistorical.descentRowsFromTrail(...a),
   get IDEA_SIZE_SCALE_REF() { return ideaSizeLib.IDEA_SIZE_SCALE_REF; },
+  // BRIGHTNESS — the live share of that descent (task 1004099 / BV2.R16), on the
+  // port for the same reason size is. It is the SECOND of the two channels, and
+  // the pair is what BV2.R17 resolves the five states from: a thought that
+  // earned nothing (`hasWork: false`) and one whose work was all torn out
+  // (`share: 0`) are different objects in the sky, and only a caller holding
+  // BOTH fields can tell them apart. Shipping size without this left the ideas
+  // module able to draw how big a thought was and unable to say whether it was
+  // still alive.
+  ideaBrightness: (...a) => ideaBrightnessLib.ideaBrightness(...a),
+  ideaBrightnesses: (...a) => ideaBrightnessLib.ideaBrightnesses(...a),
   computeStreak: (...a) => streak.computeStreak(...a),
   wouldExtendStreak: (...a) => streak.wouldExtendStreak(...a),
 };

package/modules/ideas/idea-state.js

@@ -0,0 +1,254 @@
+// modules/ideas/idea-state.js — THE FIVE STATES (task 1004103 / BV2.R17,
+// goal 1000095, criterion `ideator-sky-tells-the-truth`; spec
+// docs/specs/bongos-v2-ideator-surface.md decisions 4, 19 and 20; the object
+// vocabulary is docs/design/ideator-surface-direction.md §"The five objects";
+// ADR 0322, under ADR 0321 + 0313).
+//
+// star / protostar / satellite / remnant / cold body. Every one of them is
+// DERIVED here, from facts the ledger already holds, so that no surface has to
+// infer one — which is the done-when. Three surfaces are about to draw these
+// (the room, the descent, the sky) and a state decided three times is three
+// states: the sky would say a thought went out while the room beside it still
+// called it alive, with nothing erroring and no way to tell which was right.
+//
+// THE FACTS, AND WHERE EACH COMES FROM:
+//
+//   idea_inbox.status            'open' | 'promoted' | 'discarded' | 'merged'
+//                                — the triage verdict (core_195).
+//   brightness.hasWork           has this thought been paid for anything at all
+//   brightness.share             how much of that payout is still alive
+//   brightness.attributable      whether the removal facts could be read
+//                                — all three from economy's idea-brightness.js,
+//                                reached through the `reward` port.
+//   tasks[].goal_id / .status    the BINDING home and whether it awaits a nod
+//                                — from the trail's lineage join.
+//
+// THE ORDER OF THE TESTS IS THE DESIGN, and each step below is a decision
+// someone could reasonably have made the other way:
+//
+// 1. MERGED WINS OVER EVERYTHING — a merged thought is a satellite even when it
+//    earned money of its own. `modules/ideas/trail-size.js` is emphatic that a
+//    merged idea keeps its OWN size (stream 1 books against the idea whose
+//    lineage row named the shipping task), and that stays true: this changes
+//    what the thought IS, never what it earned. The design's word is "it orbits
+//    that one now" — once folded, it is no longer its own point in the sky, and
+//    drawing it as an independent star beside the thought that absorbed it would
+//    show one idea twice.
+//
+// 2. WORK BEATS A DISCARD. A discarded idea that nevertheless caused shipped,
+//    paid work is not a cold body — the design defines that object as "it never
+//    ignited, so it has no size at all", which is a stated PROPERTY, and testing
+//    work first is what keeps the property true by construction instead of by
+//    hope. This is reachable: triage can discard a duplicate whose twin already
+//    routed and paid, and `updateIdea` never touches the ledger.
+//
+// 3. REMNANT NEEDS EVIDENCE, NEVER ITS ABSENCE. `share === 0` says the project
+//    confirmed every piece of this descent gone. `share === null` says the
+//    removal facts could not be read at all (lifecycle off, port unregistered) —
+//    brightness is explicit that those are different answers, and treating the
+//    second as the first would draw every star in the instance as a hollow ring
+//    the moment a module failed to mount. An unreadable idea with work is a
+//    star, carrying `attributable: false` so a surface can say the brightness is
+//    unknown rather than full.
+//
+// 4. A PROTOSTAR IS THE ABSENCE OF WORK, not the presence of a status. Both an
+//    'open' idea nobody has touched and a 'promoted' one whose task has not
+//    shipped yet are unignited, which is exactly right: ignition is being paid
+//    for something, not being converted into a row.
+//
+// POSITION IS A SEPARATE AXIS from the object, and it is the half the design
+// says the object alone cannot carry: a protostar INSIDE A WELL has a home and
+// awaits a nod; one in OPEN SPACE has nothing holding it. It is computed for
+// every state (a star has a position too) but it is only load-bearing for a
+// protostar, where it is the difference between "someone must act" and "nobody
+// has claimed this".
+//
+// WHY `suggested_goal_id` IS NOT A WELL. It sits on the row, it names a goal,
+// and it is the wrong fact: `projection.js` records that it is STRICTLY
+// ADVISORY — the routing HINT on a filing that did NOT convert, with the binding
+// home being `tasks.goal_id`. Reading it here would draw a protostar sitting
+// inside a well that never caught it, and put it in a nod queue no one can act
+// on because no task exists to promote.
+//
+// PURE. No DB, no clock, no port — the resolver takes facts and returns an
+// answer, the way `routing.js` takes a filing and returns a landing. The one
+// async function in the file is the trail attacher at the bottom, which fetches
+// the brightness half and then calls the pure one. `tests/idea_state.mjs` drives
+// every cell of the matrix DB-free because of that split.
+
+const api = require('../../src/module-api');
+
+// The five objects, spelled once. Exported so a renderer switches on the same
+// vocabulary the resolver emits rather than a hand-copied list of strings that
+// can drift by a hyphen.
+const IDEA_STATES = Object.freeze({
+  STAR: 'star',
+  PROTOSTAR: 'protostar',
+  SATELLITE: 'satellite',
+  REMNANT: 'remnant',
+  COLD_BODY: 'cold-body',
+});
+const IDEA_STATE_VALUES = Object.freeze(Object.values(IDEA_STATES));
+
+// The two positions. `null` is not a third one — it is "this thought has no
+// task in any goal", which IS open space; the field is never null.
+const IDEA_POSITIONS = Object.freeze({ WELL: 'well', OPEN_SPACE: 'open-space' });
+
+// The task status that means "routed into a goal, one Metic+ promote from
+// claimable" — the nod the landing matrix soft-lands every non-bug at
+// (`routing.js` HARD_LAND_KINDS). Spelled here rather than imported because
+// routing.js is about the DECISION to land and this is about reading the result
+// of one; the coupling is the status vocabulary, which is core's.
+const AWAITING_NOD_STATUS = 'backlog';
+
+// A positive integer id as it arrives off a row, where a bigint may be a string.
+// Never coerced with Number() — the guard economy's idea-size.js uses, for the
+// same precision reason.
+function idOf(v) {
+  return /^[1-9]\d*$/.test(String(v)) ? String(v) : null;
+}
+
+// taskFactsFromIdeaRow — the { goalId, status } pairs an idea's state depends
+// on, taken off a trail row.
+//
+// It lives here, with the resolver that consumes it, for the reason economy's
+// `descentRowsFromTrail` lives with the pricing rather than in the trail: a
+// hand-built projection at the call site is a copy that can quietly stop
+// carrying a field the consumer needs, and nothing errors when it does.
+//
+// BOTH SOURCES, because neither alone is complete. `lineage_tasks` is the full
+// answer for anything promoted since `ideas_task_lineage` existed (one idea can
+// become many tasks); `promoted_to_task_id` is the ONLY answer for promotions
+// that predate it. The legacy row is added only when the lineage does not
+// already name that task, so an idea carrying both is not counted twice.
+function taskFactsFromIdeaRow(row) {
+  const out = [];
+  const seen = new Set();
+  const lineage = Array.isArray(row && row.lineage_tasks) ? row.lineage_tasks : [];
+  for (const t of lineage) {
+    if (!t) continue;
+    const taskId = idOf(t.task_id);
+    if (taskId) seen.add(taskId);
+    out.push({ taskId, goalId: idOf(t.goal_id), status: t.status || null });
+  }
+  const legacyId = idOf(row && row.promoted_to_task_id);
+  if (legacyId && !seen.has(legacyId)) {
+    out.push({
+      taskId: legacyId,
+      goalId: idOf(row.promoted_task_goal_id),
+      status: row.promoted_task_status || null,
+    });
+  }
+  return out;
+}
+
+// resolveIdeaState — the whole decision, pure.
+//
+//   status        the idea's triage status
+//   hasWork       brightness.hasWork — has it been paid for anything
+//   share         brightness.share — the live fraction, or null if unreadable
+//   attributable  brightness.attributable — whether the removal facts were read
+//   tasks         taskFactsFromIdeaRow(row)
+//
+// Returns { state, position, wellGoalId, awaitingNod, brightness, hasWork,
+//           attributable }
+//
+// `brightness` is passed straight through so a surface drawing the object and
+// its dimness reads ONE answer: a renderer that took the state from here and the
+// share from somewhere else could draw a full-brightness remnant.
+//
+// A MISSING BRIGHTNESS IS NOT ZERO WORK. When the caller has no brightness at
+// all (the `reward` port is absent), `hasWork` arrives undefined and the idea
+// resolves on its status alone — an unignited-looking protostar — with
+// `attributable: false` saying the money could not be read. Defaulting `hasWork`
+// to false would be the same claim; the flag is what stops a surface from
+// stating it.
+function resolveIdeaState({ status = null, hasWork = false, share = null, attributable = false, tasks = [] } = {}) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  // A well is a goal that actually HOLDS one of this thought's tasks.
+  const inGoal = list.find((t) => t && t.goalId);
+  const wellGoalId = inGoal ? inGoal.goalId : null;
+  const position = wellGoalId ? IDEA_POSITIONS.WELL : IDEA_POSITIONS.OPEN_SPACE;
+  // The nod is a property of a TASK, so it is asked of every task in a goal and
+  // not only of the one that named the well: an idea that became two tasks, one
+  // promoted and one still at backlog, still has something awaiting a person.
+  const awaitingNod = list.some((t) => t && t.goalId && t.status === AWAITING_NOD_STATUS);
+
+  const common = {
+    position,
+    wellGoalId,
+    awaitingNod,
+    brightness: share,
+    hasWork: hasWork === true,
+    attributable: attributable === true,
+  };
+
+  // 1. Folded into another thought — whatever else is true of it.
+  if (status === 'merged') return { state: IDEA_STATES.SATELLITE, ...common };
+
+  // 2/3. It ignited. Only CONFIRMED removal of the whole descent puts it out.
+  if (hasWork === true) {
+    const dead = attributable === true && share === 0;
+    return { state: dead ? IDEA_STATES.REMNANT : IDEA_STATES.STAR, ...common };
+  }
+
+  // 4. Declined at triage, having caused nothing.
+  if (status === 'discarded') return { state: IDEA_STATES.COLD_BODY, ...common };
+
+  // 5. Filed, not yet ignited. `position` is the half that matters here.
+  return { state: IDEA_STATES.PROTOSTAR, ...common };
+}
+
+// attachStateToTrail — hangs `state` on every idea of a trail page, in place,
+// mirroring attachDescentToTrail / attachSizeToTrail so the route composes the
+// three the same way.
+//
+// COMPOSED AFTER attachSizeToTrail, and that ordering saves a whole second
+// ledger read: size leaves `idea.size` carrying economy's own `byTask`
+// breakdown, which is exactly the input brightness takes its share of. Handing
+// it back means one query for the page rather than two. When an idea's size is
+// missing or carries no breakdown — the port was absent, so size is null —
+// brightness is asked for nothing and the ideas resolve on status alone.
+//
+// AN ABSENT PORT DOES NOT MAKE EVERY THOUGHT DARK. The state still resolves,
+// carrying `attributable: false`; what it must never do is silently claim the
+// sky is empty. Same posture trail-size.js takes with `size: null`.
+async function attachStateToTrail(ideas, { client = null } = {}) {
+  const list = Array.isArray(ideas) ? ideas : [];
+  if (list.length === 0) return list;
+
+  const reward = api.resolveOptional && api.resolveOptional('reward');
+  let brightnesses = null;
+  if (reward && typeof reward.ideaBrightnesses === 'function') {
+    const sizes = new Map();
+    for (const idea of list) {
+      if (idea && idea.size && idea.size.byTask instanceof Map) sizes.set(String(idea.id), idea.size);
+    }
+    brightnesses = await reward.ideaBrightnesses(
+      list.map((i) => i.id),
+      { client, ...(sizes.size === list.length ? { sizes } : {}) }
+    );
+  }
+
+  for (const idea of list) {
+    const b = brightnesses && brightnesses.get(String(idea.id));
+    idea.state = resolveIdeaState({
+      status: idea.status,
+      hasWork: b ? b.hasWork : false,
+      share: b ? b.share : null,
+      attributable: b ? b.attributable : false,
+      tasks: taskFactsFromIdeaRow(idea),
+    });
+  }
+  return list;
+}
+
+module.exports = {
+  IDEA_STATES,
+  IDEA_STATE_VALUES,
+  IDEA_POSITIONS,
+  AWAITING_NOD_STATUS,
+  taskFactsFromIdeaRow,
+  resolveIdeaState,
+  attachStateToTrail,
+};

package/modules/ideas/routes/inbox.js

@@ -43,6 +43,7 @@ const { attachDescentToTrail } = require('../trail-descent');
 // file for the same two reasons trail-descent.js is: inbox.js is at the size
 // ratchet, and a ledger read keyed by idea is a third relation again.
 const { attachSizeToTrail } = require('../trail-size');
+const { attachStateToTrail } = require('../idea-state');
 // 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)
@@ -644,6 +645,13 @@ module.exports = function buildInboxRouter() {
     // the number, and the number is a ledger read that does not depend on the
     // walk having run. One query for the whole page, through the `reward` port.
     await attachSizeToTrail(ideas);
+    // THE STATE — which of the five objects each thought is (BV2.R17). Last of
+    // the three, because it is the only one that reads the other two: it takes
+    // its share off the `byTask` breakdown size just left on the row, so the
+    // page pays for one ledger read rather than two. Derived here and not in the
+    // renderer — three surfaces are about to draw these, and a state inferred
+    // three times is three states.
+    await attachStateToTrail(ideas);
     return res.json({ builder_id: builderId, ideas, total, limit, offset });
   }, { errorCode: 'idea_trail_failed' }));