Skip to content
C.W.K.
Stream
Lesson 01 of 04 · published

The Number Nothing Else Could Read

~12 min · architecture, auditability, war-story, refactor

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"A scoring rule expressed as a browser lambda cannot be stored, served, or audited."

The version that worked

The composite lived in the frontend. Fetch the gauge rows, score each indicator, average within categories, apply weights, render the number. Recomputed on every page load, from data the page already had.

It was correct. It was fast. It had no bugs anybody found. By every test normally applied to a feature, it was fine — and it is worth sitting with that, because this is not a story about a defect. It is a story about a piece of correct code being in the wrong place, which is a much harder thing to notice.

The two consequences

The module's own docstring names them, and both are about reach rather than correctness.

It could not be read by anything else. Not the command line. Not a delegation brief. Not the assistant surface. The headline figure of the entire product existed only inside a rendering pass — which meant that the assistant docked beside the dashboard, looking at the same page, could not see the number the human was looking at.

It left no trace. Computed fresh each load, stored nowhere. So the one question a position summary invites — where has this needle been? — had no answer at all. Not an approximate answer, not an expensive one. None.

Ask what else needs to read this number. The right home for a computation is not decided by where the data happens to be available or where it is convenient to write. It is decided by the set of consumers: if the answer is only ever one rendering surface, the browser is fine. The moment a second consumer exists — a CLI, an export, a brief, an assistant, a future integration — the computation belongs where all of them can reach it.

Why this is the closing lesson's setup

This quest's frame has appeared twice already: a measurement that cannot state its own limits is not a measurement, it is a claim. The date that did not say whose calendar. The percentile that did not say how long its window was.

Here it arrives in its final form, one level up. A number computed where nothing can inspect it cannot state its limits to anyone but the person looking at the screen. Every honesty mechanism this product built — the window on the row, the reference flag, the oldest input, the source string carrying its assumption — presupposes that something other than a browser can receive them. Auditability is not a separate concern from honesty. It is the delivery mechanism for it.

I would have left it there
The frontend already had the rows. It was the natural place to write the scoring, and it worked on the first try. Nothing about it felt wrong while I was writing it, and no reviewer looking at that diff would have flagged a correct function in a sensible file. What surfaced it was not a code smell — it was a question nobody could answer: where has this needle been? The defect was invisible from inside the code and obvious the moment somebody asked the code something it could not hear.

Code

Same arithmetic, two homes, very different reach·text
IN THE BROWSER                    IN THE ENGINE
-----------------------------     -----------------------------
rendered on the dashboard   YES   rendered on the dashboard  YES
readable by the CLI          no   readable by the CLI        YES
quotable in a brief          no   quotable in a brief        YES
visible to the assistant     no   visible to the assistant   YES
stored with a data_date      no   stored with a data_date    YES
has a history to plot        no   has a history to plot      YES
weights inspectable off-page no   weights inspectable        YES

# The left column is not a worse implementation of the right one.
# It is a correct implementation with a reach of exactly one
# surface -- and every honesty field this product computes has to
# travel further than that to be worth computing.

External links

Exercise

Find a computed value in a frontend you work on that users treat as meaningful — a score, an index, a health percentage, a projection. Then list everything that might reasonably want to read it: an alerting rule, an export, a report, an API consumer, a support tool. If that list has more than one entry and the computation lives in the client, you have found the same thing.
Hint
The fastest diagnostic is the history question. Ask 'what was this value last Tuesday?' If nothing in the system can answer, the value is being displayed rather than recorded — and displayed-only numbers cannot be audited, compared, or cited, no matter how correct they are.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.