UK local solve doctrine: uniform operator, declared bounds, past-cap census (#495 increment 4)

[MaxGhenis]

What

Increment 4 of the UK dense/local epic (#495): the local solve becomes one uniform operator with declared bounds and first-class written-off-row diagnostics, per the #492/#493 doctrine — no per-target calibration knobs.

Past-cap census (#492 A, ported to the local solve)

past_cap_census in local_solver.py: counts of target rows past the loss cap at initialization and at the final weights, the rows that escaped back inside, the rows frozen past the cap throughout, and — the silent-triage class #492 measured on Build N — the rows pushed out during the solve, listed row by row with area/metric labels and before/after scaled errors (bounded list with an explicit truncation flag). Every solve_stacked_local_weights result now carries the census (StackedLocalSolveResult.past_cap_census, additive field), so both the research harness and the doctrine path get the observability for free.

The doctrine surface (local_doctrine.py)

• UKLocalSolveDoctrine — a frozen, self-validating contract: declared loss cap, declared weight-ratio stretch bound, and closed vocabularies for the scale rule (default_target_loss_scales only — the canonical target-defined scales) and target weighting (uniform only). A future family-level weighting would be a new reviewed rule name here, never a per-target vector.
• UK_LOCAL_SOLVE_DOCTRINE — the reviewed instance; UK_LOCAL_TARGET_LOSS_CAP = 10.0 and UK_LOCAL_MAX_WEIGHT_RATIO = 100.0 declare the current defaults as the explicit contract. Revising either is a doctrine change that must edit this module and its pinned test, which forces review. (max_weight_ratio anchors differently per arm: 5x vs design (dense) but ~25x effective (sparse refit re-anchors) — declare one stretch contract #493's one-stretch-contract adjudication may revise the ratio; the increment-6 candidate review adjudicates the cap against measured fit — the point of this increment is that the values are declared and uniform, not what they are.)
• solve_uk_local_weights_under_doctrine — the release path's solve. Structurally knob-free: target_loss_weights, target_loss_scales, target_loss_cap, and max_weight_ratio do not exist on its signature; passing them is a TypeError by construction, not a runtime flag. A tampered doctrine instance fails its own validation before any solve runs.

The low-level solve_stacked_local_weights remains the research harness (experiments legitimately pass explicit vectors); the doctrine wrapper is what increment 6 wires into the release build.

Testing

7 new tests: census transition classification on a hand-built 4-row case (escaped/frozen/pushed-out each exercised, row labels checked), default-scale semantics + shape validation, census carried on a real small solve, pinned doctrine constants, tampered-bound refusals (cap ≤ 0/NaN, ratio ≤ 1, unknown rules), the no-knobs signature guarantee, and declared-bound application (stretch bound holds on solved weights; non-doctrine object refused). Existing solver/runner tests untouched and green; ruff check clean.

Part of #495.

🤖 Generated with Claude Code

[MaxGhenis]

Cross-family review completed (sol adversarial pass, fable adjudication) — all three blockers confirmed and fixed in the second commit:

1. The candidate path bypassed the doctrine (build_local_candidate(solver_options={"target_loss_weights": …}) reached the research solver directly). Fixed: under_doctrine=True is now the release mode — per-target/bound solver options are refused by name and the solve routes through the doctrine wrapper. The research path stays available, but a doctrine candidate is now structurally distinguishable.
2. dataclasses.replace() minted a validated-but-revised contract (cap 77) and the wrapper forwarded it. Fixed by removing the injection point entirely: solve_uk_local_weights_under_doctrine takes no doctrine parameter — the bounds always come from the reviewed module constant. This also moots the copy/subclass/__setattr__ tampering class (finding 5): there is nothing to inject into.
3. The 100-row pushed-out truncation contradicted the "every row" promise. Fixed: unbounded by default; max_listed_rows is an explicit opt-in bound with a truncation flag, and the solver path never bounds it.

Should-fixes: census now mirrors the canonical loss's refusals (non-finite estimates/targets, zero/non-finite scales raise instead of silently classifying inside the cap — and the solver's own canonical-loss call would refuse such inputs before the census anyway, so the two stay consistent); the doctrine path refuses duplicate (area_type, area_code, metric) rows as implicit per-target weights (finding 6); summarize_local_candidate reports past-cap counts and write_local_candidate_outputs persists past_cap_census.json (finding 7); exact-tie strictly-greater semantics pinned by test and the brittle Adam-monotonicity/nanmax assertions replaced (finding 9). Test coverage added for each (28 tests in the affected files, all green).

Sol's no-issue verifications worth keeping on record: max_weight_ratio is a hard closing cap in the optimizer (so the stretch-bound test is sound), strictly-greater cap semantics match the torch gradient, the additive result field breaks no in-repo consumer, and census cost is linear at the 20k-target scale.