@bongos/core 1.19.922 → 1.19.923

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.922",
-  "core_contract": "1.19.922",
-  "source_commit": "b57f79a73cefa42840ff10d77aab958af1fe4ed4",
+  "core_version": "1.19.923",
+  "core_contract": "1.19.923",
+  "source_commit": "f854693589aaf4e6736cbe02c05c3fd5eb2f2ca1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T20:40:52.111Z",
+  "built_at": "2026-09-20T22:19:24.521Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 510,
+    "docs_redacted": 511,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2309,
+    "functional_verbatim": 2311,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2845,
-  "tree_sha256": "36516d370c40955c53b7b0b70845d49e03d34aaecf7d5e58a54bf78ed454f694",
+  "file_count": 2848,
+  "tree_sha256": "c600fca8af8dd65a3567fe7851b2ead8bc6c08f43dcb3b1b4964957c5c734e1a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2099,10 +2099,15 @@
       "mode": "0000644",
       "sha256": "3a743808de440eebd5fcdd74a4c88e41acc82cc02ce5632cb392b2aa0c05b48e"
     },
+    {
+      "path": "docs/adr/0322-a-remnant-needs-evidence-and-merged-wins.md",
+      "mode": "0000644",
+      "sha256": "6a4ad58720701e760068d5ce1761733790beef0a142aa31a08782d029cc7a390"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "caece332e048f6ee15517740255c4d715efc025c82756ac095ccde7814b60daa"
+      "sha256": "7c66ecbd1940f3cdd830f0fb4acf65c41178807a431bb8fab382e4b8a0dbc8ae"
     },
     {
       "path": "docs/api-reference.md",
@@ -2672,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "d657d8b2fc7eb2bb4379a22a41d95b835ac655848626120a2218ab7603df5313"
+      "sha256": "2dc422992b2c8e66db2eb3e7492abb35d061caf0ea2e3cc1ad492d0b4b8083b4"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4272,7 +4277,7 @@
     {
       "path": "modules/economy/reward.js",
       "mode": "0000644",
-      "sha256": "ef4b939d83324c927dd1b1c8e3200212d0b5da973a87db6f9810c9c7edb942ad"
+      "sha256": "79f225665dfc84fce1c50d01a25bbf81986c91047732d04113f24a68f766d29a"
     },
     {
       "path": "modules/economy/routes/cost.js",
@@ -5399,6 +5404,11 @@
       "mode": "0000644",
       "sha256": "363598b5905c850967b407f20110a1d9e9d5b1090a958700cb6a4ed5cea70d80"
     },
+    {
+      "path": "modules/ideas/idea-state.js",
+      "mode": "0000644",
+      "sha256": "e516f7951b91234c1f9dc6e327dc7365b6f6c9aad69bb3a85835061e2d072253"
+    },
     {
       "path": "modules/ideas/inbox.js",
       "mode": "0000644",
@@ -5477,7 +5487,7 @@
     {
       "path": "modules/ideas/routes/inbox.js",
       "mode": "0000644",
-      "sha256": "5ec576c26e46c8a27cd3b40d400abd177f4bdf1f2124e286a294fa58a809489a"
+      "sha256": "c302e5cd180ce9a6253ab30fad24b970d06f33f0916ac5d922323e536da7b213"
     },
     {
       "path": "modules/ideas/routing.js",
@@ -5507,7 +5517,7 @@
     {
       "path": "modules/ideas/trail.js",
       "mode": "0000644",
-      "sha256": "35dfa6abb78efdac695b89805d660ff4bb0e0d2bc2587f0d1945310dcffb2980"
+      "sha256": "5ea6bad2296406f56bcf3a00f040ce78a789f24fc0d7d5b933e1526cbbb97cd2"
     },
     {
       "path": "modules/lifecycle/CLAUDE.md",
@@ -7902,12 +7912,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "0169c3fafa67ebf63c9ae35566e8104bcf210ae80973c8e1837874109fe85354"
+      "sha256": "baab771a63f97afcbcfa72e466c8e3bcdb220724bf1a0fd2046e078c88c31cc4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b62dd828c8e8b167dfc4bca7d54fdec8c76b13f89a44e61365d48962abf77ba9"
+      "sha256": "ff37869714eeb7c99b2120171573cee5a434667baa4eb7bc76a87755f4a67214"
     },
     {
       "path": "public-docs/index.html",
@@ -9907,7 +9917,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "86c69951f0059e5374245ef798c5cd24cd82d836a4ccf706e80f186de986b473"
+      "sha256": "7c96d3ff9b319a6e4b6e640b01d8e8d3d61a341efb292359c35c495a938eacd5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12034,6 +12044,11 @@
       "mode": "0000644",
       "sha256": "8bfc36537ffccae702e74e8763534fa535486a2eb8bbf9ee546a2c7368d1dc6b"
     },
+    {
+      "path": "tests/idea_state.mjs",
+      "mode": "0000644",
+      "sha256": "f71f7007d72689e865b1945feac66012398b38557affdc776d0a6abdc2140e65"
+    },
     {
       "path": "tests/idea_task_descent.mjs",
       "mode": "0000644",

package/docs/adr/0322-a-remnant-needs-evidence-and-merged-wins.md

@@ -0,0 +1,110 @@
+# ADR 0322 — The five states are derived once, and a remnant needs evidence
+
+- **Status:** Accepted
+- **Date:** 2026-09-20
+- **Task:** [task 1004103](https://cloudbongos.com/builders#/task/1004103) (BV2.R17, goal 1000095 — BONGOS-V2)
+- **Spec:** `docs/specs/<redacted>.md` decisions 4, 19 and 20; criterion `ideator-sky-tells-the-truth`
+- **Design of record:** `docs/design/ideator-surface-direction.md` §"The five objects"
+- **Under:** [ADR 0321](0321-brightness-is-a-weighted-share-and-the-targets-are-a-row.md), [ADR 0313](0313-a-removal-is-proposed-by-the-ship-and-confirmed-by-a-person.md), [ADR 0312](0312-provenance-is-a-second-ideas-owned-edge-table.md)
+
+## Context
+
+The ideator surface draws a thought as one of five objects: **star** (it caused work that
+is still alive), **protostar** (filed, not yet ignited), **satellite** (folded into another
+thought), **remnant** (it burned, then the project removed it) and **cold body** (declined
+at triage, so it never ignited and has no size at all). Dim and dark are different states
+and must be different objects, not one dot at two opacities.
+
+Three surfaces are about to draw them — the room (BV2.R03), the descent (R10) and the sky
+(R20) — and the spec's own phrasing is that every state must be *computed from the ledger,
+and no surface has to infer one*.
+
+The facts already exist. `idea_inbox.status` carries the triage verdict (`open`,
+`promoted`, `discarded`, `merged`; `core_195`). ADR 0321 gave economy `ideaBrightnesses()`,
+returning `hasWork`, `share` and `attributable` per idea. `tasks.goal_id` and `tasks.status`
+say where a thought's work sits and whether it awaits a nod. Nothing was missing; what was
+missing was one place that reads them.
+
+## Decision
+
+**One resolver, `modules/ideas/idea-state.js`, and no surface decides a state.** A state
+inferred in three renderers is three states: the sky can say a thought went out while the
+room beside it still calls it alive, with nothing erroring and no way to tell which is
+right. The resolver is pure — facts in, object out — the way `routing.js` is pure about a
+landing. `attachStateToTrail` is the one async wrapper, composed on the trail route after
+`attachSizeToTrail`.
+
+**Brightness goes on the `reward` port.** `ideas` may not reach `credit_log` any other way
+(ADR 0083 rule 1), and it already declares `reward` in `consumes`, so no new dependency
+edge. Shipping size without brightness had left the module able to draw how big a thought
+was and unable to say whether it was still alive.
+
+**The order of the tests is the decision**, and each step could have gone the other way:
+
+1. **Merged wins over everything.** A folded thought is a satellite even when it earned
+   money of its own — and it *keeps* that money; `trail-size.js` is emphatic that stream 1
+   books against the idea whose lineage row named the shipping task. This changes what the
+   thought **is**, not what it earned. Letting work win here draws a satellite as an
+   independent star beside the thought that absorbed it: one idea, twice in the sky.
+2. **Work beats a discard.** The design defines a cold body as one that *"never ignited, so
+   it has no size at all"* — a stated property, and testing work before status is what
+   makes it true by construction rather than by hope. It is reachable: triage can discard a
+   duplicate whose twin already routed and paid, and `updateIdea` never touches the ledger.
+3. **A remnant needs evidence, never the absence of an answer.** `share === 0` means the
+   project confirmed every piece of the descent gone. `share === null` means the removal
+   facts could not be read at all — ADR 0321 is explicit that those are different answers.
+   An idea with work and no readable facts is a **star** carrying `attributable: false`, so
+   a surface says "unknown" rather than "full". Reading a falsy share as death turns one
+   unmounted module into a sky of hollow rings.
+4. **A protostar is the absence of work, not the presence of a status.** Ignition is being
+   *paid* for something, not being converted into a row, so a promoted-but-unshipped idea is
+   still unignited — which is exactly the state the nod queue exists for.
+
+**Position is a second axis**, because the design says the object alone cannot carry it: a
+protostar **in a well** has a home and awaits a nod; one in **open space** has nothing
+holding it. The resolver returns `position`, `wellGoalId` and `awaitingNod` for every state
+(a star has a position too), and the nod is asked of *every* task rather than only the one
+that named the well — an idea that became two tasks, one promoted and one still at
+`backlog`, still has something waiting on a person.
+
+**`suggested_goal_id` is deliberately not a well.** It sits on the row, it names a goal, and
+it is the wrong fact: `projection.js` records it as strictly advisory — the routing hint on
+a filing that did **not** convert, with `tasks.goal_id` as the binding home. Reading it here
+would draw a protostar inside a well that never caught it and put it in a nod queue nobody
+can act on, because no task exists to promote. The binding fact is now selected on both of
+the trail's task joins (`trail.js`), which costs no extra round trip.
+
+**The page reads the ledger once.** `attachSizeToTrail` leaves economy's own `byTask`
+breakdown on each row and brightness takes its share of exactly that, so the state attach
+hands it straight back. All of the sizes or none: a partial map reads a missing entry as
+"no work", which would draw a paid star as a protostar.
+
+**An absent `reward` port does not empty the sky.** The states still resolve on status
+alone, carrying `attributable: false` — the same posture `trail-size.js` takes with
+`size: null`.
+
+## Consequences
+
+- `GET /inbox/by-builder/:id` now returns `state` per idea beside `size` and
+  `descent_tasks`. Additive; no existing consumer reads it yet, and R03/R10/R20 will.
+- The five objects are spelled once (`IDEA_STATES`), so a renderer switching on hand-copied
+  strings cannot drift by a hyphen and silently draw nothing.
+- Nothing here writes, and no credit moves. ADR 0313 stands: `shipped` is terminal, and
+  only the picture changes.
+- `tests/idea_state.mjs` (31 cases, DB-free). The ordering, the zero-over-zero edge, the
+  well and the trail SQL are each mutation-probed.
+
+## Rejected
+
+- **Resolving the state in each renderer.** The cheapest thing to write and the reason the
+  done-when says "no surface has to infer one".
+- **Deriving the state from `share` alone.** It merges a protostar with a remnant — the
+  precise distinction the two channels exist to draw, and the one BV2.R19's proof checks.
+- **Treating an unreadable `share` as zero.** "We could not look" is not "everything was
+  removed"; ADR 0321 pays for that distinction upstream and discarding it here wastes it.
+- **Status-first ordering** (a discarded idea is always a cold body). It contradicts the
+  object's own stated property the moment triage discards something that already paid.
+- **Reading `suggested_goal_id` as a well.** Advisory by construction; it would populate a
+  nod queue with entries nothing can act on.
+- **A sixth object for "unknown brightness".** The vocabulary is the owner's and is five;
+  the uncertainty is carried as a flag on the answer, not as a new thing in the sky.

package/docs/adr/README.md

@@ -413,3 +413,4 @@ This keeps the decision history honest and traceable.
 | 0319 | [**A removal verdict is a row beside the question, because both answers close it the same way** ([task 1004095](https://cloudbongos.com/builders#/task/1004095), goal 1000095 — BONGOS-V2). [ADR 0313](0313-a-removal-is-proposed-by-the-ship-and-confirmed-by-a-person.md) settled that a ship deleting an earlier shipped task’s files files a QUESTION and a person answers it; task 1004090 built the question and nothing could answer it. Building the answer surfaced the property that decides the design: a proposal is a question, not work, so CONFIRMING and DISMISSING both leave nothing to build and both end the task at `abandoned` — meaning a status alone records neither, and brightness could not tell the star it must dim from the one it must not. ADR 0313 had already rejected the obvious alternative (a `removed` status; `shipped` is terminal and much of the ledger leans on it — a removal is a fact recorded BESIDE work, not a new terminal state). Decision: `lifecycle_removal_verdicts` (migration `lifecycle_009`), PRIMARY KEY on `proposal_task_id` so one proposal holds one answer ever — a second decide is REFUSED (409), never upserted and never an idempotent 200, because overwriting destroys the record that a person answered differently; the row is locked `FOR UPDATE` first, so simultaneous Confirm and Dismiss cannot both read “undecided”, and `ALREADY_DECIDED` is checked BEFORE `PROPOSAL_CLOSED` because an answered proposal is also abandoned and the useful message is the one naming the earlier verdict. The verdict and the status change commit in ONE transaction. What this does NOT ship is the target list: the affected tasks and paths stay PROSE in the proposal body (the owner’s 2026-09-20 decision, since [ADR 0242](0242-a-cascade-is-a-declaration-table-on-the-event-that-already-exists.md) forbids widening the runner to fan out), and nothing here parses it — brightness designs that storage. What brightness does get is structured: the verdict plus `ship_task_id`, denormalised out of the `source_ref` that encodes it as a string nothing can join on. Surface: spec decision 15’s “existing awaiting-nod surface” is the CARD, not the QUEUE — [ADR 0299](0299-the-nod-queue-stays-scoped-to-routed-filings.md) keeps that queue scoped to routed filings and a removal proposal has no idea lineage at all, so it gets its own slice on the same card at the same floor. The PERMISSION is reused (`task.promote`, Metic+, read and write both) and the VERB is not: no existing route means “that work is genuinely gone”, and `/tasks/:id/abandon` would close the question without recording which answer was given. Top-level `/removal-proposals` rather than `/tasks/removal-proposals`, because the manifest mounts `tasks` first and its `/tasks/:id` swallows a later file’s literal segment. Rot is INHERITED: `backlog` is rottable and `abandoned` is not, so an unanswered proposal rots and an answered one leaves the feed with no code written for either — pinned against the rot module’s own exported vocabulary. Rejected: the status as the record; parsing the body at confirm time; widening the nod queue; separate `/confirm` and `/dismiss` routes; upserting a second verdict; a `LIKE ‘prefix%’` match (a rule key may contain an underscore, which is a LIKE wildcard).](0319-a-removal-verdict-is-a-row-beside-the-question.md) | ideas / lifecycle |
 | 0318 | [**Listing a file for task affinity is not claiming to own it** ([task 1004110](https://cloudbongos.com/builders#/task/1004110), goal 1000095 — BONGOS-V2). The case [ADR 0314](0314-module-protection-is-per-path-not-per-module.md) named and left open, closed by neither of the two routes it predicted. `builder-settings` derived `protected` — Archon-only to scope a goal to — on exactly one glob, `src/bongos/routes/me.js`, caught by the blanket `src/bongos/routes/` prefix. **That glob was never an ownership claim:** `MODULE_GLOBS` listed it for task AFFINITY and said in the same comment that the `GET /me` aggregator stays a thin core facade, and `isProtected()` cannot tell the two apart. **Both predicted routes were measured and rejected.** Narrowing the blanket prefix: all eighteen files under `src/bongos/routes/` are protected by that prefix AND NOTHING ELSE, so narrowing unwalls `auth.js`, `builders.js`, `backup.js` and `core-update.js` together — now pinned as a tripwire test rather than left as a caution. Moving `me.js` into `modules/builder-settings/`: the aggregator resolves TEN module ports (`lifecycle`, `reward`, `onboarding`, `government`, `specialities`, `grade`, `box`, `art` ×2, `discord`) and `builder-settings` is one of them, so hosting it inside one module means resolving nine foreign ports from the inside — the `core -> module` edge [ADR 0083](0083-modular-architecture-strangler-build-plan.md) rule 1 forbids. Decision: **ownership follows what the file is** — `me.js` moves to `kernel`, which already owns `src/bongos/routes/security.js`. This is 0314 one step on: owning the command is not owning the authority, and **being listed next to a module is not owning it either**. **Rejected: a general affinity tier** in `MODULE_GLOBS` mirroring `isCommandPath` — the audit does not support it. Three other modules (`kernel`, `devsecops`, `methodology`) are also protected only by paths outside their own directory, but in each the foreign path genuinely IS the domain; `builder-settings` was the only module protected by a path its own source called core, so a new tier would be a new place for a hole to hide, built for a population of one. `protectedModules()` goes 9 -> 8. **The wall that matters does not move:** a sub-Metic builder touching `/me` is still refused by `checkPermissionPaths`, asserted directly rather than assumed. The sixteen still-unowned route files remain [task 1004116](https://cloudbongos.com/builders#/task/1004116), whose option (a) this de-risks.](0318-listing-a-file-for-task-affinity-is-not-owning-it.md) | permissions / module scope |
 | 0321 | [**Brightness is a payout-weighted share, and a removal's targets are rows** ([task 1004099](https://cloudbongos.com/builders#/task/1004099), goal 1000095 — BONGOS-V2). Size is an idea's total ideator payout and never falls; brightness is how much of that work is still alive, and the pair is what lets a thought whose version was torn out draw LARGE AND DARK rather than merging with one that never mattered. Two things had to be settled. **The removal facts were stored in the wrong direction**: [ADR 0319](0319-a-removal-verdict-is-a-row-beside-the-question.md) gave a confirmed removal a row carrying the verdict and `ship_task_id` — the task whose merge DELETED the files — and deliberately left out the tasks whose work was removed, saying brightness would design its own storage when it needed one. Those are different rows under different ideas, so reading one as the other dims the wrong star while looking like a working query. `<redacted>` stores `(proposal_task_id, removed_task_id, paths)` at PROPOSAL time, from the SAME derivation objects the proposal body renders as prose — one derivation, two renderings, so they cannot disagree and `removal-proposals.js` keeps its refusal to parse a body back. Proposal time and not verdict time because the attribution comes from capped, rate-limited GitHub commit-history reads that only exist while the cascade runs. NOT a runner fan-out ([ADR 0242](0242-a-cascade-is-a-declaration-table-on-the-event-that-already-exists.md)): the rule still files one task; this records a side fact about it. `ON CONFLICT DO NOTHING`, never `DO UPDATE`, since a degraded second walk finds FEWER paths and must not erase a good first read — and the writer runs on the cascade's SKIPPED row too, so a re-ship repairs what a derivation outage missed. **The share is weighted by PAYOUT, not by task count**, or deleting a one-line fix dims a star as hard as deleting the feature; weighting by what each hop earned also makes 'large and dead' exact, and makes the two channels a share of ONE number rather than two unrelated measurements. Basis is paid + estimated to match size, which required `priceDescentForIdea`/`ideaSizes` to return a per-task `byTask` summing EXACTLY to `credits` — including ledger payments for tasks the descent no longer reaches, which `idea-size.js` keeps in `credits` so size cannot fall and which would otherwise make the parts sum to less than the whole. Three edges, each silent: an idea that earned nothing is `share: 1, hasWork: false`, because zero over zero is not zero and a protostar is not a remnant (the BV2.R19 distinction); an unreadable removal port gives `share: null, attributable: false`, because 'could not look' is not 'nothing was removed'; and a CONFIRMED removal naming no target dims nothing at all — brightness cannot know which idea — so `countUnattributedConfirmed()` exists to say the gap out loud instead of quietly brightening the sky. Brightness lives in `economy` beside size and reaches lifecycle through the new `lifecycle.removals` port, resolved OPTIONALLY and NOT declared in `consumes` (declaring it would turn 'lifecycle off' into 'instance will not start' — the `ideas.descent` precedent). **No credit is clawed back and nothing here writes**: ADR 0313 stands, `shipped` is terminal, only the picture changes. Rejected: parsing the proposal body (ADR 0319 already refused it — a human-facing line shape fails silently when reworded); re-deriving at verdict time; treating `ship_task_id` as the removed task; counting tasks rather than payouts; clamping the share at the top, which would hide the anomaly it claims to prevent.](0321-brightness-is-a-weighted-share-and-the-targets-are-a-row.md) | ideas / economy |
+| 0322 | [**The five states are derived once, and a remnant needs evidence** ([task 1004103](https://cloudbongos.com/builders#/task/1004103), goal 1000095 — BONGOS-V2). The ideator surface draws a thought as one of five objects — star, protostar, satellite, remnant, cold body — and three surfaces are about to draw them (the room, the descent, the sky). Every fact already existed: `idea_inbox.status` (`core_195`), [ADR 0321](0321-brightness-is-a-weighted-share-and-the-targets-are-a-row.md)’s `hasWork` / `share` / `attributable`, and `tasks.goal_id` + `tasks.status`. What was missing was ONE place that reads them: a state inferred in three renderers is three states, and the sky can say a thought went out while the room beside it still calls it alive, with nothing erroring. **Decision:** one pure resolver (`modules/ideas/idea-state.js`), brightness exposed on the `reward` port (ideas may not reach `credit_log` any other way — [ADR 0083](0083-modular-architecture-strangler-build-plan.md) rule 1 — and already declares `reward` in `consumes`), and the ORDER of the tests IS the decision. **MERGED wins over everything:** a folded thought keeps its own money (`trail-size.js` is emphatic) but is no longer its own point in the sky, so letting work win draws one idea twice, beside the thought that absorbed it. **WORK beats a DISCARD:** a cold body “never ignited, so it has no size at all” is a stated PROPERTY, and testing work first makes it true by construction — triage really can discard a duplicate whose twin already routed and paid, and `updateIdea` never touches the ledger. **A REMNANT needs EVIDENCE, never the absence of an answer:** `share: 0` is a confirmed removal, `share: null` is an unreadable one, and ADR 0321 pays for that distinction upstream — so an idea with work and no readable facts is a STAR carrying `attributable: false`, because reading a falsy share as death turns one unmounted module into a sky of hollow rings. **A PROTOSTAR is the absence of WORK, not of a status:** ignition is being PAID for something, so a promoted-but-unshipped idea is still unignited, which is exactly what the nod queue exists for. **Position is a second axis** (`well` / `open-space` / `awaitingNod`) because the design says the object alone cannot carry it, and the nod is asked of EVERY task, not only the one that named the well. **`suggested_goal_id` is deliberately NOT a well** — `projection.js` records it as strictly advisory, the routing hint on a filing that did not convert, so reading it would put a thought in a nod queue with no task to promote; the binding `tasks.goal_id` now rides on both of the trail’s task joins at no extra round trip. The page reads the ledger ONCE: the state attach hands economy back the `byTask` breakdown size just computed, all of them or none (a partial map reads a missing entry as “no work” and draws a paid star as a protostar). An absent `reward` port does not empty the sky — states still resolve, flagged unattributable. Nothing writes; ADR 0313 stands. Rejected: resolving in each renderer; deriving from `share` alone (it merges a protostar with a remnant, the exact BV2.R19 distinction); treating an unreadable share as zero; status-first ordering; reading the hint as a home; a sixth object for “unknown brightness” (the vocabulary is the owner’s and is five — the uncertainty is a flag on the answer, not a new thing in the sky).](0322-a-remnant-needs-evidence-and-merged-wins.md) | ideas / economy |

package/docs/module-api-changelog.md

@@ -2318,5 +2318,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.920 with no explicit bump. run 35534076467. (task 1002620)
   1.19.922 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.921 with no explicit bump. run 35536293721. (task 1002620)
+  1.19.923 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.922 with no explicit bump. run 35541278656. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

package/modules/ideas/trail.js

@@ -42,6 +42,16 @@ const { skillFrictionHiddenClause } = require('./skill-friction');
 // first. Both are returned: the lineage array is the complete answer, the legacy
 // column is the only answer for promotions that predate the lineage table. The
 // LATERAL is bounded by the page window, so this stays one query, not an N+1.
+//
+// `goal_id` RIDES ALONG ON BOTH TASK JOINS (task 1004103 / BV2.R17) because it
+// is what tells a protostar in a WELL from one in OPEN SPACE — the distinction
+// the design makes position carry, and the reason the nod queue is a thing a
+// person can see rather than a list someone must remember to open
+// (docs/design/ideator-surface-direction.md). It is the BINDING home for "which
+// goal"; `idea_inbox.suggested_goal_id`, already on the row, is a HINT about a
+// filing that did not convert and is deliberately not what ./idea-state.js
+// reads. Two nullable columns on joins the query already makes, so this costs
+// no round trip.
 const IDEA_TRAIL_DEFAULT_LIMIT = 20;
 const IDEA_TRAIL_MAX_LIMIT = 100;
 
@@ -68,6 +78,7 @@ async function listIdeaTrailForBuilder(builderId, { limit = IDEA_TRAIL_DEFAULT_L
     `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
             pt.title  AS promoted_task_title,
             pt.status AS promoted_task_status,
+            pt.goal_id AS promoted_task_goal_id,
             mi.title  AS merged_into_idea_title,
             mi.status AS merged_into_idea_status,
             COALESCE(lin.tasks, '[]'::json) AS lineage_tasks
@@ -78,7 +89,8 @@ async function listIdeaTrailForBuilder(builderId, { limit = IDEA_TRAIL_DEFAULT_L
        LEFT JOIN LATERAL (
          SELECT json_agg(json_build_object(
                   'task_id', l.task_id, 'origin', l.origin,
-                  'title', lt.title, 'status', lt.status
+                  'title', lt.title, 'status', lt.status,
+                  'goal_id', lt.goal_id
                 ) ORDER BY l.task_id) AS tasks
            FROM ideas_task_lineage l
            JOIN tasks lt ON lt.id = l.task_id

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.922",
+  "version": "1.19.923",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.922",
+      "version": "1.19.923",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.922",
+  "version": "1.19.923",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.922'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.923'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/idea_state.mjs

@@ -0,0 +1,399 @@
+// tests/idea_state.mjs
+//
+// task 1004103 (BV2.R17, goal 1000095, criterion `ideator-sky-tells-the-truth`)
+// — THE FIVE STATES resolve from ledger facts. 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".
+//
+// WHAT CAN GO SILENTLY WRONG HERE, which is what this file is aimed at:
+//
+//   * A PROTOSTAR DRAWN AS A REMNANT. An idea that has earned nothing comes back
+//     from brightness as `share: 1, hasWork: false` — LIT. Resolve the state off
+//     the share alone and a freshly-filed thought is indistinguishable from one
+//     whose version the project tore out, which is the exact distinction the two
+//     channels exist to draw. §2.
+//   * "COULD NOT LOOK" READ AS "EVERYTHING WAS REMOVED". `share: null` means the
+//     removal facts were unreadable, not that nothing survived. A resolver that
+//     treats a falsy share as dead turns one unmounted module into a sky of
+//     hollow rings. §3.
+//   * A COLD BODY WITH MONEY ON IT. The design defines a cold body as having no
+//     size at all; triage can discard a duplicate whose twin already paid, so
+//     the property only holds if work is tested BEFORE the status. §4.
+//   * A MERGED THOUGHT DRAWN TWICE. It keeps its own size (trail-size.js is
+//     emphatic), so an order that lets work win would draw a satellite as an
+//     independent star beside the thought that absorbed it. §5.
+//   * THE WELL READ OFF THE HINT. `suggested_goal_id` names a goal and is
+//     strictly advisory — the routing hint on a filing that did NOT convert. Read
+//     it as a home and a protostar joins a nod queue nobody can act on, because
+//     no task exists to promote. §6.
+//   * THE BINDING FACT NEVER REACHING THE RESOLVER. The state can only tell a
+//     well from open space if the trail actually selects `goal_id`; drop it and
+//     every thought in the instance quietly reads as homeless. §7 reads the
+//     statement.
+//   * THE ATTACH NEVER BEING CALLED. A resolver nothing invokes passes its whole
+//     suite and reaches no surface — this module's own history (a dead cascade
+//     rule) says so. §8 drives the real attacher and §9 holds the route wiring.
+//   * THE PAGE PAYING TWICE. Brightness takes its share of the same `byTask`
+//     breakdown size already computed; not handing it back doubles the ledger
+//     reads on every trail view, with nothing rendering differently. §8.
+//
+// DB-free: the reward port is a stub and the resolver is pure.
+//
+// Run:  node tests/idea_state.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 api = require('../src/module-api.js');
+const state = require('../modules/ideas/idea-state.js');
+const reward = require('../modules/economy/reward.js');
+
+const { resolveIdeaState, taskFactsFromIdeaRow, attachStateToTrail, IDEA_STATES, IDEA_POSITIONS } = state;
+
+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))}`); }
+}
+
+// A lit idea that has been paid: what brightness returns for a live descent.
+const LIVE = { hasWork: true, share: 1, attributable: true };
+// The same descent, every piece of it confirmed removed.
+const DEAD = { hasWork: true, share: 0, attributable: true };
+// A thought that has earned nothing — LIT, because nothing has been taken away.
+const UNIGNITED = { hasWork: false, share: 1, attributable: true };
+
+// ---------------------------------------------------------------------------
+// 1. the five objects, each from its facts
+// ---------------------------------------------------------------------------
+
+await test('§1 star — it caused work that is still alive', () => {
+  const s = resolveIdeaState({ status: 'promoted', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.STAR);
+  assert.equal(s.brightness, 1);
+});
+
+await test('§1 star — partly removed is DIM, not out', () => {
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0.4, attributable: true });
+  assert.equal(s.state, IDEA_STATES.STAR, 'graded, not binary — it goes out only when nothing survives');
+  assert.equal(s.brightness, 0.4, 'and the surface reads the dimness off the same answer');
+});
+
+await test('§1 protostar — filed, not yet ignited', () => {
+  assert.equal(resolveIdeaState({ status: 'open', ...UNIGNITED }).state, IDEA_STATES.PROTOSTAR);
+});
+
+await test('§1 protostar — PROMOTED but unshipped is still unignited', () => {
+  // Ignition is being paid for something, not being converted into a row. A
+  // status-first resolver calls this a star and the sky claims work that has not
+  // happened.
+  const s = resolveIdeaState({
+    status: 'promoted', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: '9', status: 'ready' }],
+  });
+  assert.equal(s.state, IDEA_STATES.PROTOSTAR);
+});
+
+await test('§1 satellite — folded into another thought', () => {
+  assert.equal(resolveIdeaState({ status: 'merged', ...UNIGNITED }).state, IDEA_STATES.SATELLITE);
+});
+
+await test('§1 remnant — it burned, then the project removed it', () => {
+  const s = resolveIdeaState({ status: 'promoted', ...DEAD });
+  assert.equal(s.state, IDEA_STATES.REMNANT);
+  assert.equal(s.hasWork, true, 'and it KEEPS its size — large and dead is the whole point');
+});
+
+await test('§1 cold body — declined at triage, having caused nothing', () => {
+  const s = resolveIdeaState({ status: 'discarded', ...UNIGNITED });
+  assert.equal(s.state, IDEA_STATES.COLD_BODY);
+  assert.equal(s.hasWork, false);
+});
+
+// ---------------------------------------------------------------------------
+// 2. zero over zero — the sharpest edge brightness hands over
+// ---------------------------------------------------------------------------
+
+await test('§2 an idea that earned nothing is a PROTOSTAR, never a remnant', () => {
+  // brightness returns share 1 / hasWork false for it on purpose. The failure
+  // this pins is a resolver that asks "is the share zero" of an idea whose share
+  // was never a fraction of anything.
+  const fresh = resolveIdeaState({ status: 'open', hasWork: false, share: 1, attributable: true });
+  const torn = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0, attributable: true });
+  assert.equal(fresh.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(torn.state, IDEA_STATES.REMNANT);
+  assert.notEqual(fresh.state, torn.state, 'these two must never be the same object');
+});
+
+await test('§2 hasWork is what separates them, not the share', () => {
+  // Same share on both sides; only hasWork differs.
+  const a = resolveIdeaState({ status: 'open', hasWork: false, share: 0, attributable: true });
+  const b = resolveIdeaState({ status: 'open', hasWork: true, share: 0, attributable: true });
+  assert.equal(a.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(b.state, IDEA_STATES.REMNANT);
+});
+
+// ---------------------------------------------------------------------------
+// 3. a remnant needs EVIDENCE of removal, never the absence of an answer
+// ---------------------------------------------------------------------------
+
+await test('§3 unreadable removal facts give a STAR, flagged unattributable', () => {
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: null, attributable: false });
+  assert.equal(s.state, IDEA_STATES.STAR, 'we could not look — that is not evidence the work is gone');
+  assert.equal(s.attributable, false, 'and the surface is TOLD, so it can say "unknown" rather than "full"');
+  assert.equal(s.brightness, null);
+});
+
+await test('§3 a share of 0 with attributable false is still not a remnant', () => {
+  // Defensive: brightness never emits this pair, and a resolver that reads the
+  // share without the flag would call an unreadable idea dead the day it did.
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0, attributable: false });
+  assert.equal(s.state, IDEA_STATES.STAR);
+});
+
+// ---------------------------------------------------------------------------
+// 4. work beats a discard — the cold body's stated property
+// ---------------------------------------------------------------------------
+
+await test('§4 a DISCARDED idea that caused paid work is not a cold body', () => {
+  // Reachable: triage discards a duplicate whose twin already routed and paid,
+  // and updateIdea never touches the ledger. A cold body "has no size at all" —
+  // testing work first is what keeps that true by construction.
+  const s = resolveIdeaState({ status: 'discarded', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.STAR);
+});
+
+await test('§4 a discarded idea whose work was then removed is a remnant', () => {
+  assert.equal(resolveIdeaState({ status: 'discarded', ...DEAD }).state, IDEA_STATES.REMNANT);
+});
+
+// ---------------------------------------------------------------------------
+// 5. merged wins over everything — one thought, one point in the sky
+// ---------------------------------------------------------------------------
+
+await test('§5 a MERGED idea with money of its own is still a satellite', () => {
+  // It keeps its own size (trail-size.js), and that stays true — this changes
+  // what the thought IS, not what it earned. Letting work win here draws it as an
+  // independent star beside the thought that absorbed it.
+  const s = resolveIdeaState({ status: 'merged', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.SATELLITE);
+  assert.equal(s.hasWork, true, 'and its size is reported, not erased');
+});
+
+await test('§5 a merged idea whose work was removed is a satellite too', () => {
+  assert.equal(resolveIdeaState({ status: 'merged', ...DEAD }).state, IDEA_STATES.SATELLITE);
+});
+
+// ---------------------------------------------------------------------------
+// 6. position — the distinction the object alone cannot carry
+// ---------------------------------------------------------------------------
+
+await test('§6 a protostar in a WELL awaits a nod', () => {
+  const s = resolveIdeaState({
+    status: 'open', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: '77', status: 'backlog' }],
+  });
+  assert.equal(s.position, IDEA_POSITIONS.WELL);
+  assert.equal(s.wellGoalId, '77');
+  assert.equal(s.awaitingNod, true, 'this is what makes the nod queue something a person can SEE');
+});
+
+await test('§6 a protostar in OPEN SPACE has nothing holding it', () => {
+  const s = resolveIdeaState({ status: 'open', ...UNIGNITED, tasks: [] });
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+  assert.equal(s.wellGoalId, null);
+  assert.equal(s.awaitingNod, false);
+});
+
+await test('§6 suggested_goal_id is a HINT and never a well', () => {
+  // It names a goal and it is strictly advisory: the routing hint on a filing
+  // that did not convert. Reading it here puts a thought in a nod queue with no
+  // task to promote.
+  const row = { id: '1', status: 'open', suggested_goal_id: '77', lineage_tasks: [] };
+  const s = resolveIdeaState({ status: row.status, ...UNIGNITED, tasks: taskFactsFromIdeaRow(row) });
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+  assert.equal(s.wellGoalId, null);
+});
+
+await test('§6 a task in a goal that is past the nod is a well, not a queue', () => {
+  const s = resolveIdeaState({
+    status: 'promoted', ...LIVE,
+    tasks: [{ taskId: '5', goalId: '77', status: 'shipped' }],
+  });
+  assert.equal(s.position, IDEA_POSITIONS.WELL);
+  assert.equal(s.awaitingNod, false);
+});
+
+await test('§6 the nod is asked of EVERY task, not only the one that named the well', () => {
+  // One idea, two tasks: one promoted, one still at backlog. Something still
+  // awaits a person, and a resolver that only inspected the first task misses it.
+  const s = resolveIdeaState({
+    status: 'promoted', ...LIVE,
+    tasks: [
+      { taskId: '5', goalId: '77', status: 'ready' },
+      { taskId: '6', goalId: '77', status: 'backlog' },
+    ],
+  });
+  assert.equal(s.awaitingNod, true);
+});
+
+await test('§6 a backlog task with NO goal is not a nod queue entry', () => {
+  // The nod is a promote within a goal; a goal-less backlog row has no well to
+  // be promoted inside.
+  const s = resolveIdeaState({
+    status: 'open', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: null, status: 'backlog' }],
+  });
+  assert.equal(s.awaitingNod, false);
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+});
+
+// ---------------------------------------------------------------------------
+// 7. the facts off a real trail row — and the statement that carries them
+// ---------------------------------------------------------------------------
+
+await test('§7 lineage tasks and the legacy column are BOTH read, and never twice', () => {
+  // lineage_tasks is the complete answer since ideas_task_lineage; the legacy
+  // promoted_to_task_id is the only answer for promotions that predate it. An
+  // idea carrying both must not count that task twice.
+  const both = taskFactsFromIdeaRow({
+    promoted_to_task_id: '5', promoted_task_status: 'ready', promoted_task_goal_id: '77',
+    lineage_tasks: [{ task_id: 5, status: 'ready', goal_id: 77 }],
+  });
+  assert.equal(both.length, 1, 'the same task named twice is one task');
+  const legacyOnly = taskFactsFromIdeaRow({
+    promoted_to_task_id: '5', promoted_task_status: 'backlog', promoted_task_goal_id: '77',
+    lineage_tasks: [],
+  });
+  assert.equal(legacyOnly.length, 1);
+  assert.equal(legacyOnly[0].goalId, '77', 'a pre-lineage promotion still has a home');
+});
+
+await test('§7 ids survive as strings — a bigint is never coerced', () => {
+  const facts = taskFactsFromIdeaRow({ lineage_tasks: [{ task_id: 9007199254740993, goal_id: '77', status: 'ready' }] });
+  assert.equal(facts[0].goalId, '77');
+  assert.equal(typeof facts[0].taskId, 'string');
+});
+
+await test('§7 the trail SELECTS goal_id on both task joins', () => {
+  // The binding fact. Without it every thought reads as homeless and the
+  // well-vs-open-space distinction silently disappears — nothing errors, the
+  // nod queue is simply empty forever.
+  const sql = fs.readFileSync(path.join(ROOT, 'modules/ideas/trail.js'), 'utf8');
+  assert.match(sql, /'goal_id',\s*lt\.goal_id/, 'the lineage LATERAL must carry the goal');
+  assert.match(sql, /pt\.goal_id\s+AS\s+promoted_task_goal_id/, 'and so must the legacy join');
+});
+
+// ---------------------------------------------------------------------------
+// 8. the attach — including the branch where the reward port is not there
+// ---------------------------------------------------------------------------
+
+await test('§8 with the reward port absent, the states still resolve — flagged', () => {
+  // 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. An
+  // unmounted economy must not empty the sky.
+  assert.equal(api.hasProvider('reward'), false, 'nothing has registered it yet');
+  return attachStateToTrail([{ id: '7', status: 'open', lineage_tasks: [] }]).then((ideas) => {
+    assert.equal(ideas[0].state.state, IDEA_STATES.PROTOSTAR);
+    assert.equal(ideas[0].state.attributable, false, 'the money could not be read, and it says so');
+  });
+});
+
+// The port stub. It records what it was ASKED, which is what §8's one-read
+// property is pinned on.
+const asked = [];
+api.registerProvider('reward', {
+  ...reward,
+  async ideaBrightnesses(ids, opts = {}) {
+    asked.push({ ids: ids.map(String), sizes: opts.sizes || null });
+    const out = new Map();
+    for (const id of ids.map(String)) {
+      if (id === '7') out.set(id, { ...LIVE, credits: 40, removedTasks: [] });
+      if (id === '8') out.set(id, { ...DEAD, credits: 40, removedTasks: [{ taskId: '500', credits: 40 }] });
+      if (id === '9') out.set(id, { ...UNIGNITED, credits: 0, removedTasks: [] });
+    }
+    return out;
+  },
+});
+
+await test('§8 the attach hangs one state per idea, off the real brightness', async () => {
+  const ideas = [
+    { id: '7', status: 'promoted', lineage_tasks: [{ task_id: 500, goal_id: 77, status: 'shipped' }] },
+    { id: '8', status: 'promoted', lineage_tasks: [{ task_id: 500, goal_id: 77, status: 'shipped' }] },
+    { id: '9', status: 'open', lineage_tasks: [] },
+  ];
+  await attachStateToTrail(ideas);
+  assert.equal(ideas[0].state.state, IDEA_STATES.STAR);
+  assert.equal(ideas[1].state.state, IDEA_STATES.REMNANT);
+  assert.equal(ideas[2].state.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(ideas[2].state.position, IDEA_POSITIONS.OPEN_SPACE);
+});
+
+await test('§8 an already-computed size is HANDED BACK, so the page reads once', async () => {
+  // attachSizeToTrail leaves economy's own byTask breakdown on the row, and
+  // brightness takes its share of exactly that. Not passing it makes every trail
+  // view pay for the ledger twice, and nothing renders differently.
+  asked.length = 0;
+  const withSize = [
+    { id: '7', status: 'promoted', lineage_tasks: [], size: { credits: 40, byTask: new Map([['500', 40]]) } },
+  ];
+  await attachStateToTrail(withSize);
+  assert.ok(asked[0].sizes instanceof Map, 'the breakdown must travel with the request');
+  assert.equal(asked[0].sizes.get('7').credits, 40);
+
+  // And a page where the sizes are NOT all in hand asks for none of them, rather
+  // than handing over a partial map: brightness reads a missing entry as "no
+  // work", which would draw a paid star as a protostar.
+  asked.length = 0;
+  await attachStateToTrail([
+    { id: '7', status: 'promoted', lineage_tasks: [], size: { credits: 40, byTask: new Map() } },
+    { id: '8', status: 'promoted', lineage_tasks: [], size: null },
+  ]);
+  assert.equal(asked[0].sizes, null, 'all of them or none — a partial map silently unlights a star');
+});
+
+await test('§8 an empty page costs nothing at all', async () => {
+  asked.length = 0;
+  assert.deepEqual(await attachStateToTrail([]), []);
+  assert.equal(asked.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// 9. the wiring — a resolver nothing calls reaches no surface
+// ---------------------------------------------------------------------------
+
+await test('§9 the trail route attaches the state, AFTER the size', async () => {
+  const route = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/inbox.js'), 'utf8');
+  assert.match(route, /require\('\.\.\/idea-state'\)/, 'the route must import it');
+  const size = route.indexOf('await attachSizeToTrail(ideas)');
+  const stateAt = route.indexOf('await attachStateToTrail(ideas)');
+  assert.ok(size > 0 && stateAt > 0, 'both attaches must be called on the trail');
+  assert.ok(stateAt > size, 'state reads the byTask breakdown size leaves behind, so it runs second');
+});
+
+await test('§9 the reward port exposes brightness at all', async () => {
+  // The ideas module may only reach credit_log through this port (ADR 0083 rule
+  // 1). Shipping brightness without putting it on the port leaves the module able
+  // to draw how big a thought is and unable to say whether it is still alive.
+  assert.equal(typeof reward.ideaBrightnesses, 'function');
+  assert.equal(typeof reward.ideaBrightness, 'function');
+});
+
+await test('§9 the five objects are spelled ONCE, and the module exports them', async () => {
+  // A renderer switching on hand-copied strings drifts by a hyphen and draws
+  // nothing, silently.
+  assert.deepEqual(
+    [...state.IDEA_STATE_VALUES].sort(),
+    ['cold-body', 'protostar', 'remnant', 'satellite', 'star']
+  );
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);