guard(reach): pin every declared floor to its population (#15928)

repo_tests/_reach.py

@@ -73,6 +73,35 @@ class Reach:
     discover: Callable[[Path], Sequence[object]]
     floor: int
     what: str
+    #: How far the live population may sit **above** ``floor`` before
+    #: ``reach_declarations_test`` demands the floor be ratcheted up (#15928).
+    #:
+    #: Zero — equality — is right whenever ordinary work does not move the
+    #: number: a fixed set of workflows, of provider baselines, of scrub sites.
+    #: A population that grows with almost every commit (tracked files, dict
+    #: literals) cannot be equality-pinned without failing unrelated PRs, and
+    #: states a band instead.
+    #:
+    #: The question that decides it is **"does normal work move this number?"**
+    #: -- not "how much slack feels safe". Slack chosen by feel is what this
+    #: field exists to stop: the two guards that adopted this module first
+    #: declared floors of 500 and 1000 against a live population of 5,599.
+    growth: int = 0
+    #: Discovered items this guard is expected to be unable to **complete** --
+    #: unreadable, unparseable, skipped for cause (#15928). Declared separately
+    #: from ``growth`` because one floor serves two populations: ``examined()``
+    #: bounds what ``discover`` returned, ``completed()`` bounds what the guard
+    #: finished, and the floor has to clear the lower one while the meta-test
+    #: measures the higher.
+    #:
+    #: Folding this into ``growth`` is what broke the first version of this
+    #: change. ``audio-extension-allowlist`` discovers 5,601 files and completes
+    #: 5,337, so a single band of 500 spent 264 of itself on the skip gap before
+    #: buying one file of growth headroom -- and the tree consumed the remainder
+    #: within the hour. **A number that silently spends most of itself on a
+    #: different quantity cannot be chosen well**, which is the argument for two
+    #: names rather than a bigger one.
+    skips: int = 0
 
     def examined(self, root: Path) -> Sequence[object]:
         """Discover under *root*, or fail loudly having found implausibly little.
@@ -106,12 +135,32 @@ def _require(self, count: int, verb: str, what: str) -> None:
             )
 
 
-def declare(name: str, *, discover: Callable[[Path], Sequence[object]], floor: int, what: str) -> Reach:
+def declare(
+    name: str,
+    *,
+    discover: Callable[[Path], Sequence[object]],
+    floor: int,
+    what: str,
+    growth: int = 0,
+    skips: int = 0,
+) -> Reach:
     """Register a reach declaration and return it.
 
     Registration is the point: an undeclared guard is invisible to the meta-test
     and its floor is unproven, so adoption is measurable rather than assumed.
+
+    ``floor`` is checked against the live population by
+    ``reach_declarations_test.test_every_declared_floor_is_pinned_to_its_population``
+    rather than here (#15928). Validating at declaration time would walk the
+    tree once per imported guard, and the meta-test already enumerates every
+    declaration — so the guarantee is the same and the cost is paid once.
+
+    Adoption alone does not make a floor tight. Both guards that adopted this
+    module first passed a number chosen by feel, an order of magnitude below
+    what their own ``discover`` returns, and every floor examined in review
+    during #15896, #15901 and #15913 was set the same way. The mechanism was
+    never the missing part; the number was.
     """
-    reach = Reach(name=name, discover=discover, floor=floor, what=what)
+    reach = Reach(name=name, discover=discover, floor=floor, what=what, growth=growth, skips=skips)
     REGISTRY[name] = reach
     return reach

repo_tests/audio_extension_allowlist_test.py

@@ -84,10 +84,29 @@ def _tracked_python_files(root: Path = REPO_ROOT) -> list[Path]:
 #: This sweep read every tracked file and asserted "no offenders" with no floor
 #: at all: a `git ls-files` that returned nothing — wrong cwd, a broken env, a
 #: partial checkout — passed having examined zero files (#15826).
+#: Ratcheted from 1000 (18% of the live population) under #15928. A floor that
+#: low fires only against a tree that has almost entirely stopped being read;
+#: the loss that actually happens is a narrowed glob or a moved directory,
+#: worth hundreds of files, and it cleared 1000 comfortably.
+#:
+#: `growth` is a maintenance-frequency choice, not a safety one: safety comes
+#: from the floor sitting near the population, and the band only decides how
+#: often the ratchet asks for a deliberate line. 250 absorbs ordinary churn in
+#: both directions -- files are added and deleted every week -- while staying
+#: far below the size of any subtree whose loss this exists to catch.
+#:
+#: `skips=300` is **measured, not estimated**: the pre-push hook reported
+#: `completed 5337` against `discover 5599`, a gap of 262, rounded up for churn.
+#: `growth=400` is the maintenance interval -- roughly a week of this repo's
+#: growth -- and is the only number here chosen by judgement rather than
+#: measurement. Splitting them is what makes that sentence possible; with one
+#: band nobody could say which part was which.
 REACH = declare(
     "audio-extension-allowlist",
     discover=_tracked_python_files,
-    floor=1000,
+    floor=5100,
+    growth=400,
+    skips=300,
     what="tracked python files",
 )
 

repo_tests/env_var_bare_cast_test.py

@@ -242,7 +242,30 @@ def measurement() -> Measurement:
 #: Floor on files reached, so a scanner that has stopped walking the tree
 #: fails loudly instead of passing on an empty sweep (the #15018 lesson).
 #: Measured on Dev_new_gui: comfortably above 1000 tracked, non-test .py files.
-MIN_FILES_SCANNED = 500
+MIN_FILES_SCANNED = 3000
+
+#: See `audio_extension_allowlist_test` for the derivation of `growth`.
+#:
+#: `EXPECTED_SKIPS = 0` is **measured, not assumed**. This guard discovers and
+#: parses the same set -- every file it enumerates, it completes:
+#:
+#:     discovered : 3152
+#:     completed  : 3152
+#:     GAP        : 0
+#:
+#: Re-derive rather than re-guess: enumerate `git ls-files "*.py"` through
+#: `_EXCLUDED_PATH_FRAGMENTS` and `_is_scanned`, then `ast.parse` each file
+#: catching the same `(SyntaxError, UnicodeDecodeError, OSError)` triple
+#: `measurement()` catches at the loop below.
+#:
+#: This shipped as a guess of 200 first. That was 200 units of slack buying
+#: nothing, and it sat beside `audio`'s measured 300 where it inherited an
+#: authority it had not earned -- a number chosen by feel, under the name this
+#: change added to stop numbers being chosen by feel. Declaring it honestly as
+#: a guess was weaker than measuring it. If a `completed` failure ever appears
+#: here, raise this to the number that failure hands you.
+MAX_GROWTH_BEFORE_RATCHET = 400
+EXPECTED_SKIPS = 0
 
 #: The same floor, declared so it can be **proved to fire** rather than trusted
 #: (#15826). This guard already had a floor and a vacuity test; what it did not
@@ -253,6 +276,8 @@ def measurement() -> Measurement:
     "env-var-bare-cast",
     discover=tracked_python_files,
     floor=MIN_FILES_SCANNED,
+    growth=MAX_GROWTH_BEFORE_RATCHET,
+    skips=EXPECTED_SKIPS,
     what="tracked python files",
 )
 

repo_tests/reach_declarations_test.py

@@ -28,6 +28,7 @@
 from repo_tests._reach import REGISTRY, Reach, ReachFloorError, declare
 
 _REPO_TESTS = Path(__file__).resolve().parent
+_REPO_ROOT = _REPO_TESTS.parent
 
 #: A **shrink-guard, not a reach floor.** At the current adoption count this
 #: cannot fail until someone *removes* a declaration — which is worth having,
@@ -202,3 +203,61 @@ def test_no_guard_failed_to_import() -> None:
         "these guard modules could not be imported, so their declarations (if any) are missing "
         f"from the registry: {IMPORT_FAILURES}"
     )
+
+
+@pytest.mark.parametrize("reach", _declarations(), ids=lambda r: r.name)
+def test_every_declared_floor_is_pinned_to_its_population(reach: Reach) -> None:
+    """A floor far below its population catches only total collapse (#15928).
+
+    `test_no_guard_can_succeed_against_an_empty_tree` proves a floor *fires*.
+    It cannot prove the floor is **tight**, and every floor examined in review
+    during #15896, #15901 and #15913 fired correctly against an empty tree
+    while tolerating the loss of most of a real one.
+
+    Total collapse is not the failure that happens. Partial loss is: a glob
+    narrowed, a directory moved, a change propagated to some call sites and not
+    others. A floor of 3,000 against 5,241 files detects only the loss of the
+    one tree holding 75% of them; the other five can vanish silently. That is
+    the shape this asserts against.
+
+    The rule is equality by default -- `growth=0` -- because a floor that sits
+    at its population turns any shrinkage into a failure, and shrinking a
+    guarded population is exactly the event worth a deliberate line in a diff.
+    A population that ordinary work grows declares `growth=N` and says so where
+    a reviewer sees it, rather than being pinned low and quietly meaning
+    nothing.
+
+    **This measures `discover`, and one floor serves two populations.**
+    `examined()` bounds what discovery returned; `completed()` bounds what the
+    guard finished, which is lower whenever files are skipped as unreadable or
+    unparseable -- 262 of 5,599 for `audio-extension-allowlist`. A floor that
+    satisfies this test can still fail the guard's own `completed()` check, and
+    the first version of this ratchet did exactly that: the pre-push hook
+    rejected it. `skips` now carries that gap under its own name, so `growth`
+    means only what it says and each number can be chosen against one quantity.
+
+    So this check is necessary and not sufficient. It catches a floor far below
+    its population; `completed()` remains the binding constraint. Giving the
+    two populations separate floors is the fuller fix and is not this change.
+    """
+    count = len(reach.discover(_REPO_ROOT))
+    slack = count - reach.floor
+
+    assert slack >= 0, (
+        f"[{reach.name}] floor {reach.floor} exceeds the live population of "
+        f"{count} {reach.what}. The guard cannot pass; lower the floor to "
+        f"{count} only if the population genuinely shrank."
+    )
+    allowance = reach.skips + reach.growth
+    assert slack <= allowance, (
+        f"[{reach.name}] floor {reach.floor} sits {slack} below its live "
+        f"population of {count} {reach.what}, which exceeds the declared "
+        f"allowance of {allowance} (skips={reach.skips} + growth={reach.growth}).\n"
+        f"A floor this far below what the sweep finds passes while most of the "
+        f"tree stops being reached.\n"
+        f"Raise the one that is actually short:\n"
+        f"  skips=  items this guard cannot COMPLETE (unreadable, unparseable). "
+        f"Measure it from a `completed` failure; do not estimate it.\n"
+        f"  growth= ordinary growth tolerated before a deliberate ratchet.\n"
+        f"If neither is short, the floor is stale: ratchet it toward {count}."
+    )