UK withholding: the residual check's documented gaps, and recording capped totals #1364

Follow-up to items 22 and 23 of Vahid's third review of #1344. The residual check (_ResidualCheck in uk_runtime/diagnostics.py, #1344 item 17, also in #1363) withholds published rows so that no published total less some of its published parts rests on 1 to 9 source households. Its docstring names what it does not check. This issue keeps those gaps in view for the local-line ruling and for later work.

Gaps the check does not cover

1. A total that is no row. For example, published regional rows whose sum acts as a national total, less national bands, with no national total row. The check only takes rows as totals. On the current national targets, the UC household rows are national only, so no UC case of this shape exists today.
2. A part that reaches outside its total. A row with even one household outside the total's households is not a part of it.
3. Other weights on a total the first test does not clear. The first test clears a total for combinations with weights between minus one and one. When it does not clear, the search covers three classes only: the total less a set of members whose shares stay within one, less any one part, and less any two parts. Combinations at other weights, or with three or more overlapping parts, are not searched.
4. The local line. Constituency and local-authority rows stay outside the check, as they stay outside the per-row floor. Whether a local row can give back a national one is part of the local-line ruling still owed.

A general audit (any linear combination of published rows that rests on 1 to 9 source households) is a hard problem in general. Two practical routes:

• add sums of published rows that partition one population (regional splits, sex-by-age splits) as totals that are not rows;
• run an exact tripwire on unions of small atoms of the published rows' support at release certification.

Recording capped totals (item 23)

When a total's exact search passes its node or work cap, it is searched over greedy groups instead, and a Python warning names it. On the national line this happens for the UK population total on every build, so the warning will become noise. Instead, record the capped totals in the written diagnostics, for example as a list under uk_diagnostics.model_figures_withheld, so a reader can see which totals were searched greedily. That changes the calibration-diagnostics schema (schema 8 and its committed JSON Schema), so it should be its own change.

Done when

• Each gap has either a check or a ruling that it is out of scope, written in the docstring.
• Capped totals appear in the diagnostics payload, and the warning is dropped or kept once per build.

🤖 Generated with Claude Code