diff --git a/research/cover/README.md b/research/cover/README.md index 6f1478dd7..e797f48af 100644 --- a/research/cover/README.md +++ b/research/cover/README.md @@ -162,10 +162,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 41 and 42 in `tests/test_cover.py`. Control 41 was confirmed to FAIL +against a copy of the package with the guard deleted; control 42 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 ae55439d1..49d248bce 100644 --- a/research/cover/ledger.py +++ b/research/cover/ledger.py @@ -541,6 +541,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 5df48cb00..2139fc426 100644 --- a/tests/test_cover.py +++ b/tests/test_cover.py @@ -1344,3 +1344,93 @@ def test_40_the_readme_table_is_transcribed_from_the_same_numbers(): for figure in ("2,036 total", "1,020 ACCEPTED", "1,016 REFINED", "0 REJECTED", "0 PENDING", "`17/80", "6.2286534", "6.2784424"): assert figure in text, figure + + +def test_41_NEGATIVE_CONTROL_outside_cannot_carry_a_nonzero_residual(): + """CONTROL 41. 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_42_NEGATIVE_CONTROL_the_outside_guard_is_load_bearing(): + """CONTROL 42. Control 41 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 41 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)