diff --git a/research/cover/README.md b/research/cover/README.md index 256e2c6ee..ccebc4a3a 100644 --- a/research/cover/README.md +++ b/research/cover/README.md @@ -231,10 +231,52 @@ kinds, and the distinction matters: | kind | meaning | effect on the total | |---|---|---| -| `OUTSIDE` | proved disjoint from the region by an exact rational test | contributes nothing; the total stays an enclosure | +| `OUTSIDE` | proved disjoint from the region by an exact rational test | contributes nothing; the total stays an enclosure. A non-zero `residual` here is **refused at the point of entry** — see below | | `UNRESOLVED_BOUNDARY` | straddles the boundary, unresolved at the depth limit | contributes its `residual`; without one, `covers_region=False` and `certified=False` | | `EXCLUDED` | excluded by a stated predicate (unused here) | as above | +### An `OUTSIDE` residual the total would have discarded (found 2026-09-23) + +`total()` skips every `OUTSIDE` cell with `continue` *before* it reaches the +branch that sums a residual, and until 2026-09-23 `Ledger.reject` validated the +kind, the reason and the `boundary_area_bound` but never the residual. So a +caller could reject a cell `OUTSIDE` while handing over a non-zero residual, and +the number was stored on the record, dropped from every total, and the run still +reported itself sound. On a two-cell unit cover with one cell accepted at +exactly `1` and the other rejected `OUTSIDE` carrying `[10**6, 10**6]`: + +``` +total.certified True +total.covers_region True +total.caveats () +certified_enclosure Interval(1, 1) +``` + +An enclosure of `[1, 1]` while holding a discarded possible contribution of a +million. **This was a live path, not a mutation** — nothing had to be broken to +produce those four lines. + +`reject` now requires an `OUTSIDE` cell's residual to be `None` or exactly +`[0, 0]`, and the reason is the discard rather than a contradiction. The +`[10**6, 10**6]` witness above excludes zero, so it genuinely denies OUTSIDE. +But a non-singleton enclosure that *contains* zero — `[-eps, eps]` — is a +conservative statement of a zero contribution, not a denial, and an earlier +version of this section wrongly called it one. The correction is due to a +cross-lane review on PR #38. + +The strict contract stands on the honest ground: whatever is stored here is +discarded, so a residual of non-zero **width** loses the uncertainty it +expresses, silently. Requiring exact zero makes the discard lossless. A caller +who means "zero, conservatively" writes `[0, 0]`; a caller who means "possibly +non-zero" is describing a cell that is not `OUTSIDE`. `None` and an exact `[0, 0]` are both still accepted, and the +two kinds whose residuals *are* summed still take a non-zero one — the guard is +scoped to `OUTSIDE`, so it closes the hole without removing the feature. + +Controls 33 and 34 in `tests/test_cover.py`. Control 33 was confirmed to FAIL +against a copy of the package with the guard deleted; control 34 rebuilds the +pre-guard record by hand and asserts the old behaviour, so the defect stays +demonstrable after the fix rather than surviving only as prose. + > **`boundary_area_bound` is the right name for two of those three kinds.** An > `OUTSIDE` cell is *proved disjoint* from the region: it holds no boundary and > contributes exactly zero. Its area is still retained — the recipe says retain diff --git a/research/cover/ledger.py b/research/cover/ledger.py index 74b1c13fb..109eeaba4 100644 --- a/research/cover/ledger.py +++ b/research/cover/ledger.py @@ -545,6 +545,40 @@ def reject(self, cid: str, kind: str, reason: str, raise TypeError("boundary_area_bound must be an exact Fraction") if boundary_area_bound < 0: raise ValueError("boundary_area_bound must be non-negative") + if (kind == RejectKind.OUTSIDE and residual is not None + and not (residual.lo == 0 and residual.hi == 0)): + # ``total()`` skips OUTSIDE cells before it reaches the branch that + # sums a residual, so anything handed over here is stored on the + # record and then DROPPED from every total with no caveat, no flag + # and no receipt entry -- the run still reports ``certified=True``, + # ``covers_region=True``, ``caveats=()``. + # + # The contract is therefore exactly ``None`` or exactly ``[0, 0]``, + # and the reason is the discard rather than a contradiction. An + # earlier version of this comment argued that a non-zero residual + # "denies the very rejection this call is recording". That is true + # of a witness like ``[10**6, 10**6]``, which excludes zero -- but + # it is NOT true of a non-singleton enclosure that CONTAINS zero, + # such as ``[-eps, eps]``: that is a conservative statement of a + # zero contribution, not a denial of OUTSIDE. The correction is due + # to a cross-lane review on PR #38. + # + # The strict contract still holds, on the honest ground: whatever + # is stored here is discarded, so any residual of non-zero WIDTH + # loses the uncertainty it was expressing, silently. Requiring + # exact zero makes the discard lossless. A caller who means "zero, + # conservatively" can say ``[0, 0]``; a caller who means "possibly + # non-zero" is describing a cell that is not OUTSIDE. + raise ValueError( + f"cell {cid!r} is rejected OUTSIDE, and total() discards an " + f"OUTSIDE cell's residual before summing -- so the residual " + f"must be None or exactly [0, 0] for that discard to lose " + f"nothing. This one is {residual!r}. If it excludes zero the " + f"cell can contribute and is not OUTSIDE: reject it " + f"UNRESOLVED_BOUNDARY or EXCLUDED, whose residuals are summed. " + f"If it merely has non-zero width around zero, say [0, 0] and " + f"carry the uncertainty on a cell whose residual survives." + ) rec.disposition = REJECTED rec.reject_kind = kind rec.reason = reason diff --git a/tests/test_cover.py b/tests/test_cover.py index c904b6e5f..aab101a9d 100644 --- a/tests/test_cover.py +++ b/tests/test_cover.py @@ -122,7 +122,9 @@ check_exact_partition, radial_gaussian_closed_form, rn5_annulus_bracket, rn5_annulus_polar, run, t4_polar_cover, ) -from research.cover.regions import INSIDE, OUTSIDE, STRADDLE # noqa: E402 +from research.cover.regions import ( # noqa: E402 + INSIDE, OUTSIDE, STRADDLE, two_pi_upper, +) # --------------------------------------------------------------- helpers @@ -1201,3 +1203,184 @@ def flip_second(a, b): region = rn5_annulus_bracket() for a, b in ((F(-1), F(2)), (F(0), F(3)), (F(-4), F(0)), (F(2), F(5))): assert region._axis_min_max(a, b) == (live(a, b), max(abs(a), abs(b))) + + +def test_33_NEGATIVE_CONTROL_outside_cannot_carry_a_nonzero_residual(): + """CONTROL 33. The ledger must refuse a residual it is about to discard. + + ``total()`` skips every OUTSIDE cell with ``continue`` before it reaches + the branch that sums a residual, and until this control landed ``reject()`` + validated the kind, the reason and the boundary-area bound but never the + residual. So a caller could reject a cell OUTSIDE while handing over a + non-zero residual and the number was stored on the record, dropped from + every total, and the run still reported ``certified=True``, + ``covers_region=True``, ``caveats=()``. + + Observed before the guard, on a two-cell unit cover with one cell accepted + at exactly 1 and the other rejected OUTSIDE carrying ``[10**6, 10**6]``:: + + total.certified True + total.covers_region True + total.caveats () + certified_enclosure Interval(1, 1) + + An enclosure of ``[1, 1]`` while holding a discarded possible contribution + of a million. That witness excludes zero, so it does deny OUTSIDE -- but + the contract enforced is the wider one, and for the right reason: whatever + is stored is DISCARDED, so a residual of non-zero width loses the + uncertainty it expresses even when it contains zero. Requiring exact zero + makes the discard lossless. A non-singleton enclosure around zero such as + ``[-eps, eps]`` is a conservative statement of a zero contribution and not + a contradiction; calling it one was an error in the first version of this + control, corrected after cross-lane review on PR #38. + + This is a live-path control, not a mutation control. Nothing had to be + broken to produce the number above. + """ + def two_cells(): + led = Ledger("guard", Box(F(0), F(2), F(0), F(1)), "cartesian", + integrand="f=1 reference") + led.add(Cell("a", Box(F(0), F(1), F(0), F(1)), 0)) + led.add(Cell("b", Box(F(1), F(2), F(0), F(1)), 0)) + led.accept("a", Interval.exact(F(1)), Interval.exact(F(1)), + Interval.exact(F(1))) + return led + + with pytest.raises(ValueError) as exc: + two_cells().reject("b", RejectKind.OUTSIDE, "proved disjoint", F(1), + Interval.exact(F(10) ** 6)) + assert "OUTSIDE" in str(exc.value) + assert "discard" in str(exc.value) + + # A residual that really is zero is not a contradiction, in either spelling. + two_cells().reject("b", RejectKind.OUTSIDE, "proved disjoint", F(1), None) + two_cells().reject("b", RejectKind.OUTSIDE, "proved disjoint", F(1), + Interval.exact(F(0))) + + # And the guard is scoped to OUTSIDE: the two kinds whose residuals ARE + # summed must still accept a non-zero one, or this control would have + # closed the hole by breaking the feature. + for kind in (RejectKind.EXCLUDED, RejectKind.UNRESOLVED_BOUNDARY): + led = two_cells() + led.reject("b", kind, "held", F(1), Interval.exact(F(7))) + assert led.records["b"].residual == Interval.exact(F(7)) + + +def test_34_NEGATIVE_CONTROL_the_outside_guard_is_load_bearing(): + """CONTROL 34. Control 33 must fail if the guard is removed. + + Re-implements the pre-guard ``reject`` on a copy of the record and shows + the old behaviour reappearing — the residual stored, skipped by ``total()`` + and the run still ``certified=True`` — so that control 33 is known to be + testing the guard rather than some other refusal along the path. + """ + led = Ledger("nogurad", Box(F(0), F(2), F(0), F(1)), "cartesian", + integrand="f=1 reference") + led.add(Cell("a", Box(F(0), F(1), F(0), F(1)), 0)) + led.add(Cell("b", Box(F(1), F(2), F(0), F(1)), 0)) + led.accept("a", Interval.exact(F(1)), Interval.exact(F(1)), + Interval.exact(F(1))) + + rec = led.records["b"] + rec.disposition = REJECTED + rec.reject_kind = RejectKind.OUTSIDE + rec.reason = "proved disjoint" + rec.boundary_area_bound = F(1) + rec.residual = Interval.exact(F(10) ** 6) # the guard would have refused + rec.pending_reason = None + + total = led.total() + assert total.certified and total.covers_region and total.caveats == () + assert total.certified_enclosure() == Interval.exact(F(1)) + assert led.records["b"].residual == Interval.exact(F(10) ** 6) + + +def test_35_uniform_cost_meets_its_target_and_the_published_count_is_pinned(): + """CONTROL 35. The cost figure is published in three documents. Pin it. + + ``uniform_cost`` is this package's answer to RN5's "Treat the near-axis + refinement cost explicitly", and the README stakes its standing on the + distinction: "a count, not an estimate -- exact rationals, no fit, no + sampling". Its output is quoted as exact arithmetic in three places: + ``docs/OPEN_PROBLEMS.md`` A5 ("98 x 629 = 61,642 polar cells"), + ``docs/FINDINGS_2026-09-18.md``, and ``research/cover/README.md``. + + Control 18 checks the types, that ``cells`` is the product, that the + anisotropy is 50, and that a finer target costs more. None of that + constrains the *contract* the docstring states -- that a grid of ``N_r`` + radial and ``N_t`` angular steps bounds the cell diameter by + ``dr + r_hi * 2*pi * dt <= target``. So the published number was pinned by + nothing, and this mutation survived all 48 tests: + + regions.py:323 half = target_diameter / 2 -> half = target_diameter + + Under it the annulus reports **49 x 315 = 15,435** cells rather than + 98 x 629 = 61,642, and the grid it describes has diameter bound 0.1997 + against a target of 0.1 -- it does not cover at the requested resolution, + and every document quoting 61,642 becomes false. Nothing failed. + + Three things are asserted here, all in exact rationals and never in float. + """ + a = rn5_annulus_polar() + + # (i) The contract, at several targets. + # + # NOTE ON WHAT MINIMALITY MEANS HERE, because the first draft of this + # control asserted the wrong one and failed. `uniform_cost` splits the + # budget EVENLY -- each axis is solved independently against + # `target/2` -- so each count is minimal FOR ITS HALF, and that is what + # is asserted below. The pair is NOT jointly minimal over all + # (n_r, n_t) meeting the combined bound, and this control does not + # claim it is: at target 1/3 the annulus reports 30 x 189 while + # 30 x 188 also satisfies `dr + r_hi*2*pi*dt <= 1/3`. Spending less on + # one axis to spend more on the other is a different algorithm from the + # one the docstring describes, and a test may not quietly demand it. + for target in (F(1, 10), F(1, 20), F(1, 3)): + cost = a.uniform_cost(target) + n_r, n_t = cost["radial_steps"], cost["angular_steps"] + span = a.r_hi - a.r_lo + circ = a.r_hi * two_pi_upper() + half = target / 2 + + radial_step = span / n_r + angular_extent = circ * (F(1) / n_t) + + # The headline contract the docstring states. + assert radial_step + angular_extent <= target, ( + f"target {target}: grid {n_r}x{n_t} has diameter bound " + f"{radial_step + angular_extent} > {target}; it does not cover at " + f"the resolution it claims") + assert isinstance(radial_step + angular_extent, F) + + # The even split, which is how that bound is actually achieved. + assert radial_step <= half and angular_extent <= half + + # And each count minimal for its own half -- ceil division, so one + # step fewer must overshoot. This is what the mutation breaks. + if n_r > 1: + assert span / (n_r - 1) > half, ( + f"target {target}: {n_r - 1} radial steps would also fit the " + f"half-budget, so the radial count is not minimal") + if n_t > 1: + assert circ * (F(1) / (n_t - 1)) > half, ( + f"target {target}: {n_t - 1} angular steps would also fit the " + f"half-budget, so the angular count is not minimal") + + # (ii) The figure three documents quote, pinned to the arithmetic. + published = a.uniform_cost(F(1, 10)) + assert published["radial_steps"] == 98 + assert published["angular_steps"] == 629 + assert published["cells"] == 61642 + + # (iii) And the documents themselves, so prose and arithmetic cannot drift + # apart in either direction without a failure here. + root = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + for rel, fragment in ( + (os.path.join("research", "cover", "README.md"), "61,642"), + (os.path.join("docs", "OPEN_PROBLEMS.md"), "61,642"), + (os.path.join("docs", "FINDINGS_2026-09-18.md"), "61,642")): + path = os.path.join(root, rel) + if not os.path.isfile(path): # the doc set differs per branch + continue + with open(path, encoding="utf-8") as handle: + assert fragment in handle.read(), f"{rel} no longer quotes {fragment}"