Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion research/cover/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
34 changes: 34 additions & 0 deletions research/cover/ledger.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
90 changes: 90 additions & 0 deletions tests/test_cover.py
Original file line number Diff line number Diff line change
Expand Up @@ -1201,3 +1201,93 @@ 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)
Loading