@bongos/core 1.19.920 → 1.19.922

package/docs/adr/README.md

@@ -409,5 +409,7 @@ This keeps the decision history honest and traceable.
 | 0316 | [**The ignite floor is a scheduling dial, not the trusted tier** ([task 1004084](https://cloudbongos.com/builders#/task/1004084), goal 1000095 — BONGOS-V2). BV2 decision 3 makes the ignite floor — who may turn a quick idea straight into claimable work — a per-instance setting, and decision 16 adds the descent decay rate beside it, the two to share one home. Both the spec and the seeded task described the mechanism the same way: the floor IS the `METIC_PLUS` constant in `modules/ideas/routing.js`, so this is "a setting, not a refactor". Tracing the code before building refuted that: `METIC_PLUS` is spelled once but READ for four semantically different gates — the two `decideLanding` bug branches (land at `ready` or at `backlog`), `mayProposeCriterion` (who may file a `kind='criterion-proposal'`, a planning-scope write), and the protected-scope wall in `authorizeRoutedLanding` (who may route work into the permission / ship-grade / deploy / migration core). Only the first two are the ignite floor, so making the CONSTANT configurable would mean an instance setting its floor to `xenos` — exactly the "project of one wants every thought claimable" case the owner asked for — ALSO gaining the right to file criterion-proposals and to breach the protected core. The codebase already said so in three places nobody had read into the spec: the constant's own header ("It grants nothing — the server-side rank floor and the goal's scope wall are separate, load-bearing gates"), the protected-scope branch ("the two are layers, not alternatives"), and `tests/filing_abuse_matrix.mjs`, which models the widening as an ATTACK and pins the literal. Decision: a separate dial. `modules/ideas/config.js` + `config/ideas.neutral.json` carry both knobs on the `modules/government/config.js` precedence (env -> instance root `config/ideas.json` -> core root neutral; the ADR 0268 dual-root split matters, since one root reads the host pack out of `node_modules` where `npm ci` erases it). `igniteFloor` defaults to `metic`, resolving to exactly the `METIC_PLUS` set, and is threaded into `decideLanding` as a ready-made `trustedRanks` **Set** by the callers — `routing.js` is TOLD the floor and never reads config, staying pure and DB-free — while `METIC_PLUS` stays a FIXED constant for the other two gates, neither of which takes a floor argument (pinned structurally). `descentDecayRate` defaults to 0.5 and ships with no production caller, because R11 is its intended reader and depends on the unbuilt R08 — the same deliberate slice boundary `modules/government/config.js` documents for itself, and what decision 16 asked for. Everything fails to VANILLA rather than dead: a malformed pack, an unknown rank or an out-of-band rate falls back, and an unrecognised floor yields the DEFAULT set, never an empty one (failing closed would stop every ignition on a typo). Rejected: configuring `METIC_PLUS` as written (a security widening in a config file's clothes); splitting it into four named constants (the other three want the same fixed tier, and naming them invites configuring them); having `routing.js` read the config itself (makes the landing matrix impure and untestable at a different floor). Spec decision 3's "spelled in one place" describes the intent, not the mechanism; the spec was not edited and the task description was amended in flight.](0316-the-ignite-floor-is-not-the-trusted-tier.md) | ideas / permissions |
 | 0315 | [**A plane with no proxy is refused, not given a no-op ingress** ([task 1004017](https://cloudbongos.com/builders#/task/1004017), goal 1000106 — BONGOS-V2). The piece [ADR 0306](0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md) explicitly deferred: the self-host image ships no proxy, so provisioning step 6's `<slug>.caddy` snippet write and `systemctl reload caddy` cannot work there and a child instance gets no front door. **Two failure shapes, only one visible**: a DOMAINED child already half-refused, because `caddy adapt` fails with no binary and [ADR 0303](0303-provisioning-verifies-the-base-caddyfile-and-never-edits-it.md)'s own catch turns that into a gap — but the message told the operator to add a directive to `/etc/caddy/Caddyfile`, a file the container does not have and that ADR 0303 §1 forbids provisioning from creating; a DOMAINLESS child skipped that preflight entirely (it is gated on `inst.domain`), reached step 6 and died on the `sudo` write, an uncaught throw that bypasses the `{ok:false}` pending-retry path and hard-errors the instance on attempt one — a crash recorded where a refusal was the honest answer. Decision: `ingressPlaneGap(exec)` probes the plane with `caddy version` — one cheap unprivileged read, the same posture as `checkCaddyWiring` — and both standup legs refuse with `Ingress preflight failed: …`, deliberately NOT domain-gated, because the domainless child is the one 0303 could not see. **Only a missing binary proves there is no proxy**: under remote exec `boxExec` is `ssh <host> bash -s`, so an unreachable co-hosting box throws here too, and diagnosing a network blip as 'this plane has no proxy, provision elsewhere' would be a confident wrong answer that burns the intent's retry budget — exit 127 is read as proof, anything else answers 'could not confirm a reverse proxy on this plane' with the real cause leading. The three refusals are ordered **capacity → ingress → wiring**, cheapest and most fundamental first and all before any mutation, which moves 0303's preflight behind the ADR 0285 capacity measurement; both still refuse before anything changes, so only the precedence between two refusals moves. **No ingress seam and no no-op backend**, despite the obvious symmetry with 0306: a `none` implementation whose `writeSite`/`reload` are no-ops lets the standup SUCCEED while leaving the child unreachable — neither half of the task's done-when, and exactly the silently-broken instance it exists to prevent. Does not decide: what a child's front door IS on a container plane (a published port, a bundled proxy, an explicit localhost-only shape) — a future ADR that adds one replaces this refusal rather than extending it. Teardown is left alone on purpose: it already reloads `allowFail`, and refusing there would strand a row instead of cleaning it.](0315-a-plane-with-no-proxy-is-refused-not-given-a-no-op-ingress.md) | provisioning / ingress |
 | 0317 | [**A plane that cannot give an instance its own account is refused, not given a shared uid** ([task 1004018](https://cloudbongos.com/builders#/task/1004018), goal 1000106 — BONGOS-V2). The last of the three container gaps [ADR 0306](0306-instance-supervision-is-a-seam-with-systemd-as-the-default.md) deferred, and the sibling of [ADR 0315](0315-a-plane-with-no-proxy-is-refused-not-given-a-no-op-ingress.md). [ADR 0281](0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md) makes an instance's identity its own unix account, and the unit's `User=`/`Group=` is what stops one co-tenant reading a sibling's `/proc/<pid>/environ` — where every instance's `EnvironmentFile` carries its GitHub App private key and OAuth client secret (audit B3). `useradd` needs uid 0; the self-host image is `node:22-bookworm-slim` running `USER node` with **no sudo**, so there the account cannot be created at all. **Two failure shapes, neither honest**: today step 1c's `boxExec(ensureInstanceUserCmd(...))` is not `allowFail`, so it throws AFTER every preflight passed, AFTER the status flip to `provisioning`, and — for a standalone — after a repo pull and an `npm ci`, recording a crash with the box half-changed; and tomorrow it goes quiet, because a compose self-host only stops short of step 1c by ADR 0315's coincidence, and 0315 says in its own consequences that a future front door **replaces** that refusal. Decision: `accountPlaneGap(exec, { privileged })` in `provision-repo.js` probes with `${sudo}sh -c 'test "$(id -u)" = 0'` and `provisionInstance` refuses with `Account preflight failed: …` before any mutation. **The probe runs the SAME escalation the mutation will** (`PROVISION_SUDO=1` renders the same `sudo ` prefix `ensureInstanceUserCmd` uses), so a pass is evidence rather than inference. **`sh -c`, not a bare `test`, is load-bearing**: under sudo the outer unprivileged shell would expand `$(id -u)` first and answer about the wrong user, passing on exactly the plane this refuses — and for the same reason there is no pipeline, whose exit status is its last stage's. **Only a shell that ran and answered proves it**: `boxExec` is `ssh <host> bash -s` under remote exec, so exit 1 (`test` said no) and 127 (no sudo binary) are read as proof while ssh's own 255 answers "could not confirm" with the real cause leading — ADR 0315's rule applied to a different question. Ordered **third**, after capacity and ingress and before 0303's wiring check: the first three ask about the PLANE, 0303 asks about this instance's DOMAIN, and 0315's order is extended rather than rearranged. **Rejected: accepting it** — documenting a self-host container as single-tenant with a shared uid is a silent downgrade of the vector 0281 closed, observable nowhere on the running box, and "single-tenant" is not what a container hosting several child projects is; **an identity seam with a container implementation**, because nothing exists to put behind it and a seam whose second backend does nothing is 0315's no-op wearing a seam's clothes; **probing `useradd --help` / `command -v useradd`**, which succeed unprivileged on the very image this refuses; **`${sudo}id -u` compared against `0`**, which decides on captured stdout where every sibling preflight and every test fake treats exit status as the contract; and **refusing inside step 1c**, which keeps the refusal after the status flip. Not covered, deliberately: root-but-no-`useradd` (an Alpine-style plane fails loudly at step 1c as today), and teardown (0315's reason — a refusal there strands a row instead of cleaning it). No `PROVISION_ALLOW_SHARED_UID`: a runner either reaches root on this plane or it does not.](0317-a-plane-that-cannot-give-an-instance-its-own-account-is-refused.md) | provisioning / identity |
+| 0320 | [**An empty diff is not an ungraded diff: grade the claim instead** ([task 1004011](https://cloudbongos.com/builders#/task/1004011), goal 1000118 — BONGOS-V2; scoped out of task 1003950 shape 2). `ship.js --allow-empty` closes a task that produced no committed artifact, and it used to do two things at once: set `skipGrade`, so the subagent grader never ran, and therefore route the close through `POST /tasks/:id/confirm`, gated on `task.confirm.grade_bypass` — one of [ADR 0157](0157-archon-is-rank-and-identity-only.md)'s four trust-boundary keys, so a Metic could not close an artifact-free task at all. **Both halves were wrong.** The permission was the wrong question: `grade_bypass` means *ratify past a grade that FAILED*, a genuine override of an existing verdict, and a no-artifact close has no verdict to override — charging the same key for "it was judged and rejected" and "there was nothing to judge" conflates an override with an absence. And nothing was being checked, which is the more serious half: the assertions in the handoff notes ("the premise was already fixed", "this was a pure ops verification", "the row was updated directly") went into the ledger unread, on exactly the ships where the record is the ONLY evidence that exists. A permission gate is not scrutiny — an Archon clicking confirm is not someone checking whether the claim is true. **Decision:** on `--allow-empty` the grader is not skipped, it is RE-POINTED — it grades the notes + value summary against the task description, asking whether the task is genuinely artifact-free and whether the evidence supports that. A pass is a real passing grade confirming through the ordinary rank-open path; a fail is answered with better evidence, not a key. Three sub-decisions carry it: the rubric axes are **re-asked, not replaced** (`functional_fidelity` → is this genuinely artifact-free, `code_quality` → is the evidence specific and checkable), because the gate arithmetic and `/grade-audit`, the aggregates and the cost model all read those columns and a third pair of names would mean teaching every one of them a synonym; **two generalist shots, not the four-lens panel** (Hacker/Quality/Efficiency are lenses over code — over three paragraphs of prose they are four readings of the same short text at four times the cost — so the lenses go, recorded in `signals.lenses_dropped` per the #513 trivial-diff precedent; but the panel's UNANIMOUS gate was also the cross-check that makes injection hard, and the first cut kept a single shot and lost it, so the species asks the same question twice and collapses by **unanimity, not median** — under a median the mean of a fooled 10 and a suspicious 3 is a passing 6.5 and the second reading launders the first; a split is recorded as `signals.shot_dissent`; the collapse covers ALL THREE gate axes including `confidence`, which the second grading round caught missing — it is the one axis living in `signals` rather than `rubric_scores`, and the server derives `lowConfidence` purely from the submitted value, so an honest 0.2 "I cannot judge this" averaged with a confident 0.9 would have cleared the 0.4 gate at 0.55); and the species marker lives in **`signals.no_artifact_grade`, not `grader_kind`**, because the server's `validateAndScore` hardcodes `task_grades.grader_kind` to `'subagent'` for everything on that route. **D4: every builder-controlled field is scrubbed and fenced** (`grader-workers/fence.js`, SR-15 / #995) — the panel workers have fenced the diff, title, description and value summary since #995, and this species is the worse case on both sides: the notes are not context around an artifact the model can independently check, they ARE the evidence, and a successful injection does not flip one of four workers, it closes a task past the very scrutiny this ADR added to replace the Archon-only gate. The first implementation shipped it unfenced and the grader caught it as a blocker. The no-follow rule is restated AFTER the artifact too, since the notes may run to 24,000 characters and a rule stated once at the top is a long way behind by the end of an adversarial payload. The prompt renders no changed-files or diff section at all, so the absence cannot read as the finding. No diff hash is stored — hashing the empty diff makes it a reuse key shared by every empty-diff ship of the task, handing the next close a pass this one earned. Unchanged: `--skip-grade` still reaches the Archon gate (the task 1003950 escalation split still chooses the refusal), and below the protected-path floor the server's Guard 1b (task 1002646) still fails a zero-`committed_files` pass closed, correctly — this moves the Metic-and-above case, which is the case that was filed. **Drops task 1004010**, the alternative shape — a new lower-floored permission atom for the same close — by owner decision of 2026-09-20: it answers "who may skip the check" when the better question is "why is there no check", and it permanently widens the permission surface, the same class of change the owner declined three days earlier for `version.create` ([task 1003853](https://cloudbongos.com/builders#/task/1003853), [ADR 0250](0250-strict-versioning-the-version-boundary-is-the-scope-gate.md) §6a). Also rejected: lowering the floor on the existing key (treats the gate as the point; nothing would read the notes); grading the notes with the full panel; a new pair of rubric axes for prose (honest about the measurement, but moves the gate arithmetic and every consumer of it for a naming gain).](0320-an-empty-diff-is-not-an-ungraded-diff.md) | grading / permissions |
 | 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 |

package/docs/module-api-changelog.md

@@ -2314,5 +2314,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.918 with no explicit bump. run 35531198454. (task 1002620)
   1.19.920 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.919 with no explicit bump. run 35531720944. (task 1002620)
+  1.19.921 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        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)
 ---------------------------------------------------------------------------
 ```

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;