feat(web): the serialisation contract — money as strings, values presentation-ready

[eaitbrahim]

Closes #533. Prerequisite for the rest of milestone 22 — seven downstream issues inherit this shape.

Ships keel/web/payload.py and its tests. No endpoints — those are #534.

The three rules

Money crosses the wire as strings, never as JSON numbers. JSON.parse yields IEEE-754 doubles, and keel is Decimal-only precisely because binary floats corrupt money.

Values arrive presentation-ready. The client places them; it never derives them. Every figure a user sees was computed by the Python that holds the rails — which is what makes the invariant checkable rather than merely likely, and why the client needs no decimal library at all.

Semantic state is a field, not an inference.

"pnl": { "value": "-12.34", "display": "▼ −$12.34", "state": "bad" }

A client must never decide "this is bad" from a minus sign — that is arithmetic by another route, and it relocates a judgement into the browser.

The guard is stronger than briefed

I asked for "no monetary field serialises as a number". What shipped is no JSON number anywhere — a recursive walk over the round-tripped payload, with bool excluded first since bool subclasses int.

That needs no maintained list of money fields, so it cannot rot as fields are added. It also makes the reserved sort field coherent: it would be the single, named exception.

There is a positive control (test_the_number_walker_is_proven_false_capable) so the walker cannot silently stop walking.

Four places it declined to compute

This is the invariant doing its job, and worth reading before review:

1. Notional on an open position — OpenPositionStatus carries qty and entry_price, and my own spec example shows a notional. It is not emitted. A test pins the absence and names gather_status as where the fix belongs.
2. Drawdown — drawdown_total_pct is named for a percentage but holds a fraction (guards.py:583 compares it against max_total_dd_pct: 0.20). It crosses unchanged, with no % in the display. This surfaced The browser shows the drawdown breaker 100x too small: pct() appends % to a fraction #542: render.py's pct() appends % to that same fraction, so the current browser shows a 20% drawdown ceiling as 0.20%. This PR does not inherit that bug and pins that it does not.
3. A unit on qty — the base asset is not on the report, and deriving it means parsing product_id, whose audited decoder is in guards.py and out of this layer's reach.
4. Reusing render._tone_for_rail — it falls through to "good", so "unknown" (which _rail11_status returns deliberately, because "ok" would be a lie) would style as passing.

Thinness pinning

test_console_thinness.py was extended, not forked — the module was already in its scanned set, so Rules 1–5 applied on arrival. Added Rule 6, serialiser-scoped: no .normalize(), no round(), no unscoped float(), no custom JSON encoder.

.normalize() is banned for a measured reason: it renders Decimal("50") as Decimal("5E+1"), and that exact form has previously reached the wire in this codebase.

Watched red, for the right reasons. Three deliberate mutations — a leaked raw int, normalize() in _plain, and money(qty * entry_price) — each failed the test claiming to guard it, and the computes-nothing test named the invented notional by its JSON path.

One deliberate departure from the spec

state is present on every field, including neutral and unknown. The spec's abbreviated example shows equity with only value/display.

Reason: a client testing for state's presence is branching on payload shape, which is inference by another route — the thing rule 3 exists to prevent. Recorded in the module docstring and pinned by a test.

Gates

• ruff check keel tests packages — All checks passed
• mypy — no issues in 355 source files
• pytest -q — 4585 passed, 3 skipped

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6

[eaitbrahim]

Review fixes applied — and one that found a deeper hole

All three review findings fixed. The first one turned out to be more interesting than reported.

shown_count — moved upstream, then banned structurally

shown_count is now a @property on JournalReport, following the pattern ActivityCycle.is_quiet/.key already set — derived rather than stored, because a second field holding len(self.entries) is state that can drift from the list it describes. asdict() skips properties, so keel insights journal --json is byte-identical.

The fixture now uses total_count=812 against 2 entries so the two can no longer coincide, and restoring the old shape fails as it should:

AssertionError: journal $.shown_count.value: '2' is on no report field

But that exposed a second problem. Once the property exists, len(report.entries) and report.shown_count are the same number — so reintroducing count(len(...)) passes the runtime guard. The guard compares figures and is structurally blind to that coincidence.

So len() is now banned outright in the serialiser by AST — Rule 6e:

payload:journal_payload: calls len() (line 925) -- a count on the wire
must be one the report already holds; add it to the report builder

That gives the "a second computed field cannot join silently" property by structure rather than by a maintained exception list. An allowance would have to be written entry-scoped, with its reasoning, the way float(ts) is.

stringify — JSON, not Python reprs

Nested values now cross as JSON text, each leaf normalised through stringify first so numbers inside a structure obey the top-level rules. json.dumps is called plainly — every leaf is already a string, which is why Rule 6d's default=/cls= ban costs nothing.

Depth capped at 6 with a (nested) marker: json.loads cannot build a cycle but can build a thousand nested lists, and the depth of a log line keel did not write must not decide how deep this process recurses.

New test feeds 1e50, 1e-30, [1e50] and {"deep": [{"deeper": 1e-30}]} — the scientific-notation path the original test never reached, because it only fed Decimals through report fields.

-0.00 — one reading of the sign

_magnitude now only strips and formats; _is_negative(value) is the single reading from the exact Decimal, feeding both glyph and state. Stripping rather than negating stays deliberate — abs() is arithmetic on money, which Rule 3 forbids.

• money(Decimal("-0.00")) → "$0.00", neutral, value: "-0.00" (exact value untouched)
• money(Decimal("-0.001"), signed=True) → "▼ −$0.00", bad — a loss too small to show keeps its sign and its judgement; suppressing it would report a loss as a break-even

Scope note

keel/commands/insights.py is now touched — a two-line additive property, no behaviour change — so this branch is no longer confined to keel/web/ plus tests. Flagging it because #534 builds directly on this.

Gates

ruff clean · mypy clean, 355 files · 4592 passed, 3 skipped