# Built-but-unread — the defect class, and the guard that ends it

## The class

Three consecutive orders shipped a backend-correct field that never reached a
screen. All three passed a fully green suite.

| order | what was built | why it never rendered |
|---|---|---|
| grade bands | `gradeBands.js`, six orders of work | required by no serving code |
| `91927a4` | `served_grade` on the payload | dropped at the adapter boundary |
| `3591c76` | `GradeScaleLegend.tsx` | imported by nothing |

Each was caught by luck on a later re-check, and in two of the three I had
already **reported the wiring as done**.

### Why green tests could not see it

Backend tests stop at the API payload. They prove a field is **produced** and say
nothing about whether it is **consumed**. The failure is invisible to them by
construction — not an oversight in any individual test.

### The cognitive trap, named

The difficulty pools in the backend. Deriving the grade, proving the factors,
measuring resolution — that is where the thinking happens, and by the time a
field exists on the payload it *feels* finished. The remaining step is a
three-line adapter change that nobody considers worth verifying, so it gets
claimed rather than traced. **The last inch is the one with no friction, which is
exactly why it is the one that gets skipped.**

Nothing here is a frontend-competence problem. It is that "I added the field" and
"a user can see it" are different claims, and only the first one is fun.

---

## The contract

`tests/unit/renderReachability.test.js` holds the promised-field contract — the
things the grade product commits to a user seeing:

| promise | payload | adapter | component |
|---|---|---|---|
| the served grade object | `served_grade` | `served_grade` (container) | GradeResultCard |
| what this grade means | `served_grade.meaning` | `gradeMeaning` | GradeResultCard |
| whether the band separates | `separates_from_base_rate` | `separatesFromBaseRate` | GradeResultCard |
| what the band realized | `band_realized_rate` | `bandRealizedRate` | GradeResultCard |
| which factors moved the read | `factor_adjustment` | `factorsApplied` | GradeResultCard |
| the ceiling stance | — | — | GradeScaleLegend |

Adding a served field without adding it here is allowed. Adding it **here**
without wiring it to a mounted component is not.

---

## The guard

For each promised field it traces the whole path:

```
payload field  ->  adapter consumes it  ->  component renders it  ->  component is MOUNTED
```

**"Mounted" is transitive to a Next entry point** (`page`/`layout`/`template`) —
the only thing that puts a pixel on a screen. A component that exists and renders
its field perfectly but is imported by nothing fails. Depth-limited so an import
cycle cannot hang the suite.

**Container rows are exempted explicitly, not silently.** `served_grade` is
consumed by the adapter but not rendered directly, so it carries
`container: true` plus a `rendersVia` list — and a separate assertion checks that
**every named part actually renders.** The exemption is auditable; it cannot hide
an unrendered field.

The guard also tests itself: it asserts that an orphan component reports
unmounted, and that the contract is non-empty (an empty contract would pass
vacuously — the way this guard would most plausibly rot).

### Retro-proof

Run unchanged against the tree at `3591c76`, before the wiring:

```
Tests: 11 failed, 8 passed
  ● the ceiling stance / grade scale legend — its component is MOUNTED, not merely written
  ● the served grade object — the adapter consumes it
  ● whether the band separates from the baseline — a component actually renders it
  ● what this grade means — the adapter consumes it
  ● which proven factors moved the read — a component actually renders it
  ...
```

**It names the exact three bugs.** Green on the current tree.

### One honest scope limit

`gradeBands` is **not** in the contract and would not be caught. It is a backend
module, not a promised user-facing field, and it is correctly unwired — every
band it produces collapses to base-rate at current resolution. The guard covers
*promised* fields; a backend module that should not yet render is out of scope by
design, not by oversight.

---

## In the deploy floor

The guard runs in the standing suite, so it is part of the three-gate floor:
**tests green** (now including reachability) + web build exit 0 + post-deploy
fingerprint. A future order that adds a served field without wiring it to a
mounted component fails CI rather than a hand-check three orders later.

No serving or model change in this order. `p_win` never mutated. No Bonferroni
slot.