@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/lfs/integrity/test_check.py

@@ -3,19 +3,32 @@
 test.sh builds one fixture inline (`mktemp -d`, real `git init`/`add`/`commit`
 calls, `head -c 1048577 /dev/zero`, `git lfs install --local --force`) and
 walks it through a sequence of states, asserting the gate's verdict at each
-one. Ported here as separate COMMITTED fixture directories, one per state —
-the same shift every other ported check.sh/test.sh pair in this package
-already made, and the one this task calls out `coverage.backend-ratchet`
-(`COV-002`) as its concrete precedent for. Nothing here invents a scenario
-test.sh does not have; each fixture below is named for, and traced back to,
-one specific `run_gate`/`run_gate_tree` call in test.sh.
-
-check.sh reads `:path`/`HEAD:path` (index or `HEAD`, by `ADL_GATE_PHASE`)
-and this port reads the WORKTREE file instead — see `check.py`'s module
-docstring for why (K-41: no check calls git; K-43: no phase). Concretely,
-that collapses two of test.sh's cases into one fixture each here:
-
-  test.sh case                                           -> fixture
+one. This port builds one corpus per state in `tmp_path`, at test time.
+
+WHY NOTHING IS COMMITTED. The previous port committed one directory per state.
+Those directories held `.gitattributes` lines of `*.bin filter=lfs ...`, and a
+committed `.gitattributes` also governs the OUTER repository: git-lfs converted
+the raw 1,048,577-byte `attribute-without-conversion/large file.bin` into a
+132-byte pointer at commit time, byte-identical to `clean/`. On a fresh clone
+exactly one of the `clean` / `attribute-without-conversion` tests then failed,
+depending on whether the checkout smudged LFS. A corpus generated under
+`tmp_path` lies outside the repository, so no outer filter can touch it.
+
+Every case asserts its PRECONDITION (size, first line, which files exist)
+before it is graded, and that the runner graded at least one file, so a corpus
+that is not what its name says fails loudly instead of passing for the wrong
+reason. Dispatch is the REAL registry -> `CHECKS` -> `runner.run` path: nothing
+here patches `runner.lookup`.
+
+check.sh reads `:path`/`HEAD:path` (index or `HEAD`, by `ADL_GATE_PHASE`).
+This port reads the committed size the CLI supplies in `Context.committed_sizes`
+where there is one, and otherwise the WORKTREE file -- see `check.py`'s module
+docstring (K-41: no check calls git, the CLI measures; K-43: no phase). The
+corpora below carry no committed sizes, so they all take the worktree path, and
+the section at the bottom covers the committed one. Concretely, that collapses
+two of test.sh's cases into one corpus each here:
+
+  test.sh case                                           -> corpus
   ---------------------------------------------------------------------
   pre-commit: raw blob staged, no .gitattributes           missing-filter
   pre-commit: .gitattributes matches, blob still raw       attribute-without-conversion
@@ -24,43 +37,154 @@ that collapses two of test.sh's cases into one fixture each here:
   qua_deploy: payload.dat, large, unmatched extension       unmatched-extension
   pre-commit: small.txt, silent                             clean (txt)
 
-`clean/` alone therefore stands in for THREE of test.sh's assertions (the
+`clean` alone therefore stands in for THREE of test.sh's assertions (the
 converted-pointer pass at both phases, plus the untouched small file), which
 is exact rather than a simplification: with no phase in this port, "passes at
 pre-commit" and "passes at qua_deploy" are the same claim about the same
 file.
+
+A real 132-byte pointer is at most the threshold, so `check.py` skips it on
+size alone and `clean` never reaches the pointer comparison. That comparison is
+reached only by a file OVER the threshold whose first line is the pointer
+header; the `pointer header over the threshold` cases below are the ones that
+exercise it, and they differ from `attribute-without-conversion` only in that
+first line.
 """
 
 from __future__ import annotations
 
-from helpers import corpus, corpus_files
+import hashlib
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+import pytest
+from fixture_trees import fixture_trees
+from helpers import corpus_files
 
 from adl_compliance import runner
+from adl_compliance.checks import lookup
 from adl_compliance.checks.lfs.integrity import Integrity
-from adl_compliance.core.verdict import Outcome
+from adl_compliance.core import scope
+from adl_compliance.core.verdict import Outcome, Verdict
 from adl_compliance.policy.registry import load
 
-import pytest
-
-FIXTURES = corpus("lfs", "integrity")
 ROW = load().by_id("LFS-001")
 
+AT_THRESHOLD = 1_048_576
+OVER_THRESHOLD = 1_048_577
+RAW_OVER = b"\0" * OVER_THRESHOLD
+RAW_AT = b"\0" * AT_THRESHOLD
+
+LFS_ATTRIBUTES = "*.bin filter=lfs diff=lfs merge=lfs -text\n"
+POINTER_HEADER = "version https://git-lfs.github.com/spec/v1"
+# What a real pointer says about the 1,048,577-byte blob it stands in for.
+POINTER_TEXT = (
+    f"{POINTER_HEADER}\n"
+    f"oid sha256:{hashlib.sha256(RAW_OVER).hexdigest()}\n"
+    f"size {OVER_THRESHOLD}\n"
+)
+POINTER = POINTER_TEXT.encode()
+# The same header followed by zero bytes out to OVER_THRESHOLD: a file the size
+# check does not skip whose first line IS the pointer header.
+POINTER_HEADER_OVER = POINTER + b"\0" * (OVER_THRESHOLD - len(POINTER))
+
+
+# ------------------------------------------------------------ building a corpus
+
+
+def build(tmp_path: Path, files: Mapping[str, bytes], gitattributes: str | None = None) -> Path:
+    root = tmp_path / "corpus"
+    root.mkdir()
+    if gitattributes is not None:
+        (root / ".gitattributes").write_text(gitattributes)
+    for rel, content in files.items():
+        (root / rel).write_bytes(content)
+    return root
+
+
+def first_line(root: Path, rel: str) -> str:
+    with (root / rel).open("rb") as handle:
+        prefix = handle.read(4096)
+    return prefix.split(b"\n", 1)[0].decode("utf-8", errors="replace").rstrip("\r")
+
+
+def expect_raw_blob(root: Path, rel: str, size: int) -> None:
+    """Precondition: `rel` is exactly `size` raw bytes, not a pointer."""
+    assert (root / rel).stat().st_size == size, f"{rel}: expected {size} bytes"
+    assert first_line(root, rel) != POINTER_HEADER, f"{rel} must not start with the pointer header"
+
+
+def expect_real_pointer(root: Path, rel: str) -> None:
+    """Precondition: `rel` is a genuine 3-line LFS pointer, well under the threshold."""
+    text = (root / rel).read_text()
+    lines = text.splitlines()
+    assert len(lines) == 3, f"{rel}: a pointer has exactly three lines, got {lines!r}"
+    assert lines[0] == POINTER_HEADER
+    assert re.fullmatch(r"oid sha256:[0-9a-f]{64}", lines[1]), lines[1]
+    assert re.fullmatch(r"size \d+", lines[2]), lines[2]
+    assert (root / rel).stat().st_size == len(POINTER) == 132
+    assert (root / rel).stat().st_size <= Integrity.THRESHOLD
+
+
+def expect_pointer_header_over_threshold(root: Path, rel: str) -> None:
+    """Precondition: `rel` is over the threshold AND its first line is the pointer header."""
+    assert (root / rel).stat().st_size == OVER_THRESHOLD, f"{rel}: expected {OVER_THRESHOLD} bytes"
+    assert first_line(root, rel) == POINTER_HEADER
+
+
+def expect_attributes(root: Path, present: bool) -> None:
+    assert (root / ".gitattributes").is_file() is present
+
 
-@pytest.fixture(autouse=True)
-def _wired(monkeypatch: pytest.MonkeyPatch) -> None:
-    # LFS-001 is not yet in `checks/__init__.py`'s CHECKS tuple — a later step
-    # wires this wave of checks into the registry in one shot, to avoid
-    # concurrent edits to that shared file. Until then, `runner.lookup` cannot
-    # find this row, so the dispatch path (`runner.run`) is exercised here
-    # with its one lookup call patched to resolve LFS-001 to this module's
-    # class — everything else (scope intersection, structural/graded split,
-    # verdict decision) runs for real.
-    monkeypatch.setattr(runner, "lookup", lambda gate_id: Integrity)
+def grade(root: Path) -> Verdict:
+    files = corpus_files(root)
+    verdict = runner.run(ROW, root, files)
+    assert verdict.outcome is not Outcome.COULD_NOT_RUN, verdict.render()
+    assert verdict.units > 0, f"the runner graded no files: {verdict.render()}"
+    assert verdict.units == len(files), f"graded {verdict.units} of {len(files)}: {files}"
+    return verdict
 
 
-def run(case: str) -> object:
-    root = FIXTURES / case
-    return runner.run(ROW, root, corpus_files(root))
+# --------------------------------------------------------------- the corpora
+
+
+def missing_filter(tmp_path: Path) -> Path:
+    root = build(tmp_path, {"large file.bin": RAW_OVER})
+    expect_attributes(root, present=False)
+    expect_raw_blob(root, "large file.bin", OVER_THRESHOLD)
+    return root
+
+
+def attribute_without_conversion(tmp_path: Path) -> Path:
+    root = build(tmp_path, {"large file.bin": RAW_OVER}, gitattributes=LFS_ATTRIBUTES)
+    expect_attributes(root, present=True)
+    assert "filter=lfs" in (root / ".gitattributes").read_text()
+    expect_raw_blob(root, "large file.bin", OVER_THRESHOLD)
+    return root
+
+
+def unmatched_extension(tmp_path: Path) -> Path:
+    root = build(tmp_path, {"payload.dat": RAW_OVER}, gitattributes=LFS_ATTRIBUTES)
+    expect_attributes(root, present=True)
+    assert not (root / "payload.dat").name.endswith(".bin")
+    expect_raw_blob(root, "payload.dat", OVER_THRESHOLD)
+    return root
+
+
+def clean(tmp_path: Path) -> Path:
+    root = build(
+        tmp_path,
+        {"large file.bin": POINTER, "small.txt": b"small\n"},
+        gitattributes=LFS_ATTRIBUTES,
+    )
+    expect_attributes(root, present=True)
+    expect_real_pointer(root, "large file.bin")
+    assert (root / "small.txt").stat().st_size <= Integrity.THRESHOLD
+    return root
+
+
+# ------------------------------------------------------------------ the tests
 
 
 def test_the_row_identifies_this_check() -> None:
@@ -68,10 +192,25 @@ def test_the_row_identifies_this_check() -> None:
     assert ROW.name == "integrity"
 
 
-def test_a_large_staged_blob_outside_the_lfs_filter_is_rejected() -> None:
+def test_the_real_registry_dispatch_reaches_this_check() -> None:
+    # No monkeypatch anywhere in this module: if LFS-001 fell out of
+    # `checks/__init__.py`'s CHECKS, every graded case below would come back
+    # could-not-run, and this names the cause.
+    assert lookup("LFS-001") is Integrity
+
+
+def test_the_corpus_sizes_sit_either_side_of_the_checks_threshold() -> None:
+    # If `THRESHOLD` moves, the boundary cases below stop testing the boundary;
+    # this makes that loud rather than silent.
+    assert AT_THRESHOLD == Integrity.THRESHOLD
+    assert OVER_THRESHOLD == Integrity.THRESHOLD + 1
+    assert POINTER_HEADER == Integrity.POINTER
+
+
+def test_a_large_staged_blob_outside_the_lfs_filter_is_rejected(tmp_path: Path) -> None:
     # test.sh: `run_gate pre-commit -- "large file.bin"` on a raw 1048577-byte
     # blob with no `.gitattributes` at all must fail.
-    verdict = run("missing-filter")
+    verdict = grade(missing_filter(tmp_path))
     assert verdict.outcome is Outcome.FINDINGS, verdict.render()
     assert len(verdict.findings) == 1
     finding = verdict.findings[0]
@@ -80,19 +219,19 @@ def test_a_large_staged_blob_outside_the_lfs_filter_is_rejected() -> None:
     assert finding.line is None
 
 
-def test_the_filename_with_spaces_is_not_truncated() -> None:
+def test_the_filename_with_spaces_is_not_truncated(tmp_path: Path) -> None:
     # test.sh: "A space in the name on purpose: a diagnostic that truncates at
     # the space names a file nobody can find." check.sh's own shell diagnostics
     # ran the risk of stopping at the first word; `Finding.path` and `render()`
     # are plain Python strings with no such hazard, asserted directly rather
     # than by absence.
-    verdict = run("missing-filter")
+    verdict = grade(missing_filter(tmp_path))
     assert verdict.findings[0].path == "large file.bin"
     assert "LFS-002 large file.bin: " in verdict.render()
 
 
-def test_the_finding_names_the_size_and_an_actionable_fix() -> None:
-    verdict = run("missing-filter")
+def test_the_finding_names_the_size_and_an_actionable_fix(tmp_path: Path) -> None:
+    verdict = grade(missing_filter(tmp_path))
     finding = verdict.findings[0]
     assert finding.message == (
         "large file.bin is a 1048577-byte blob entering Git without the LFS filter"
@@ -103,31 +242,605 @@ def test_the_finding_names_the_size_and_an_actionable_fix() -> None:
     )
 
 
-def test_a_matching_gitattributes_rule_does_not_excuse_a_raw_blob() -> None:
+def test_a_matching_gitattributes_rule_does_not_excuse_a_raw_blob(tmp_path: Path) -> None:
     # test.sh: "the .attributes rule is added AFTER the blob was staged...
     # This is the case that makes the `||` in the check load-bearing." A
     # `.gitattributes` match alone must not pass a file that was never
     # actually converted to an LFS pointer.
-    verdict = run("attribute-without-conversion")
+    verdict = grade(attribute_without_conversion(tmp_path))
     assert verdict.outcome is Outcome.FINDINGS, verdict.render()
     assert verdict.rules == ["LFS-002"]
     assert verdict.findings[0].path == "large file.bin"
 
 
-def test_a_correctly_tracked_lfs_pointer_and_a_small_file_both_stay_silent() -> None:
+def test_a_correctly_tracked_lfs_pointer_and_a_small_file_both_stay_silent(
+    tmp_path: Path,
+) -> None:
     # test.sh: the renormalized pointer passes at both pre-commit and
     # qua_deploy, and `small.txt` is silent throughout — three assertions,
-    # one fixture, per this test module's own docstring.
-    verdict = run("clean")
+    # one corpus, per this test module's own docstring.
+    verdict = grade(clean(tmp_path))
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
     assert verdict.findings == ()
 
 
-def test_a_large_ordinary_blob_of_an_unmatched_extension_is_reported() -> None:
+def test_a_large_ordinary_blob_of_an_unmatched_extension_is_reported(tmp_path: Path) -> None:
     # test.sh: "qua_deploy sees a large ordinary blob in HEAD" — .gitattributes
     # matches `*.bin` only, so `payload.dat` is committed as an ordinary
     # object and must still be reported.
-    verdict = run("unmatched-extension")
+    verdict = grade(unmatched_extension(tmp_path))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.rules == ["LFS-002"]
+    assert verdict.findings[0].path == "payload.dat"
+
+
+# ------------------------------------------------------ the size boundary
+
+
+def test_a_blob_of_exactly_the_threshold_is_clean(tmp_path: Path) -> None:
+    root = build(tmp_path, {"at.bin": RAW_AT})
+    expect_attributes(root, present=False)
+    expect_raw_blob(root, "at.bin", AT_THRESHOLD)
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_one_byte_over_the_threshold_is_reported_and_exactly_the_threshold_is_not(
+    tmp_path: Path,
+) -> None:
+    # Both in ONE corpus, both graded: the only difference the gate can be
+    # reacting to is the single byte.
+    root = build(tmp_path, {"at.bin": RAW_AT, "over.bin": RAW_OVER})
+    expect_attributes(root, present=False)
+    expect_raw_blob(root, "at.bin", AT_THRESHOLD)
+    expect_raw_blob(root, "over.bin", OVER_THRESHOLD)
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [finding.path for finding in verdict.findings] == ["over.bin"]
+    assert verdict.findings[0].message == (
+        "over.bin is a 1048577-byte blob entering Git without the LFS filter"
+    )
+
+
+# ------------------------------------------ the pointer branch (over threshold)
+
+
+def test_a_pointer_header_over_the_threshold_under_a_matching_rule_is_clean(
+    tmp_path: Path,
+) -> None:
+    # The only way to reach `check.py`'s pointer comparison: over the size
+    # threshold, tracked by a `filter=lfs` rule, and first line == the pointer
+    # header. The corpus is `attribute_without_conversion` with one difference,
+    # the first line -- and that one line flips the verdict.
+    root = build(tmp_path, {"large file.bin": POINTER_HEADER_OVER}, gitattributes=LFS_ATTRIBUTES)
+    expect_attributes(root, present=True)
+    expect_pointer_header_over_threshold(root, "large file.bin")
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+def test_a_pointer_header_over_the_threshold_with_no_tracking_rule_is_reported(
+    tmp_path: Path,
+) -> None:
+    # check.py: "a pointer-shaped first line alone does not excuse a path with
+    # no rule tracking it" -- both conditions are required, not either one.
+    root = build(tmp_path, {"large file.bin": POINTER_HEADER_OVER})
+    expect_attributes(root, present=False)
+    expect_pointer_header_over_threshold(root, "large file.bin")
+    verdict = grade(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.rules == ["LFS-002"]
+    assert verdict.findings[0].path == "large file.bin"
+
+
+def test_a_pointer_header_over_the_threshold_under_a_non_matching_rule_is_reported(
+    tmp_path: Path,
+) -> None:
+    root = build(tmp_path, {"payload.dat": POINTER_HEADER_OVER}, gitattributes=LFS_ATTRIBUTES)
+    expect_attributes(root, present=True)
+    expect_pointer_header_over_threshold(root, "payload.dat")
+    verdict = grade(root)
     assert verdict.outcome is Outcome.FINDINGS, verdict.render()
     assert verdict.rules == ["LFS-002"]
     assert verdict.findings[0].path == "payload.dat"
+
+
+# ------------------------------------- the committed blob, supplied by the CLI
+#
+# `cli.py` is the only module that calls git, so it hands the engine one fact per
+# tracked path: the size of the blob Git STORES for it (`Context.committed_sizes`).
+# A correctly tracked LFS file is a ~132-byte pointer in Git and the full file in
+# the worktree (the filter smudges it on checkout), so the worktree size is the
+# wrong thing to grade whenever a committed size exists. These cases pin what is
+# graded where. A path with NO committed fact is graded by its worktree file, as
+# before -- the existing cases above all run that way, with no facts at all.
+
+SMUDGED = 1_170_147  # the measured size of a real smudged LFS file on enact-combined
+POINTER_SIZE = 132  # `git cat-file -s` of the pointer committed for it
+
+
+def grade_with_facts(root: Path, committed_sizes: Mapping[str, int]) -> Verdict:
+    files = corpus_files(root)
+    verdict = runner.run(ROW, root, files, committed_sizes=committed_sizes)
+    assert verdict.outcome is not Outcome.COULD_NOT_RUN, verdict.render()
+    assert verdict.units == len(files), f"graded {verdict.units} of {len(files)}: {files}"
+    return verdict
+
+
+def test_a_smudged_lfs_file_whose_committed_blob_is_a_pointer_is_clean(tmp_path: Path) -> None:
+    # The measured false positive: Git stores 132 bytes, the worktree holds the
+    # smudged 1,170,147-byte file. Nothing under the repository can fix it -- the
+    # path IS correctly tracked -- so the gate must grade what Git stores.
+    root = build(tmp_path, {"video.webm": b"\0" * SMUDGED}, gitattributes=LFS_ATTRIBUTES)
+    assert (root / "video.webm").stat().st_size == SMUDGED > Integrity.THRESHOLD
+    verdict = grade_with_facts(root, {"video.webm": POINTER_SIZE})
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+def test_the_same_smudged_file_is_reported_when_no_committed_size_is_known(
+    tmp_path: Path,
+) -> None:
+    # The pair of the case above: the ONLY difference is the committed fact. A
+    # missing fact must never silently pass a big file.
+    root = build(tmp_path, {"video.webm": b"\0" * SMUDGED}, gitattributes=LFS_ATTRIBUTES)
+    verdict = grade_with_facts(root, {})
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [finding.path for finding in verdict.findings] == ["video.webm"]
+    assert verdict.findings[0].message == (
+        f"video.webm is a {SMUDGED}-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_a_large_committed_blob_is_reported_with_the_committed_size(tmp_path: Path) -> None:
+    root = build(tmp_path, {"photo.png": b"\0" * 2_097_152})
+    verdict = grade_with_facts(root, {"photo.png": 2_097_152})
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    finding = verdict.findings[0]
+    assert finding.rule == "LFS-002"
+    assert finding.path == "photo.png"
+    assert finding.message == "photo.png is a 2097152-byte blob entering Git without the LFS filter"
+    assert finding.fix == (
+        "add a .gitattributes rule matching photo.png to filter=lfs, run "
+        "'git lfs track' for that pattern, then re-add photo.png"
+    )
+
+
+def test_the_committed_size_decides_not_the_worktree_when_the_two_disagree(
+    tmp_path: Path,
+) -> None:
+    # Git stores 2,000,000 bytes; the worktree copy has since been cut down. What
+    # Git stores is what enters the repository, so it is still reported -- and the
+    # message names the committed size, not the 11 bytes on disk.
+    root = build(tmp_path, {"photo.png": b"shrunk\n"})
+    verdict = grade_with_facts(root, {"photo.png": 2_000_000})
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.findings[0].message == (
+        "photo.png is a 2000000-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_a_committed_blob_exactly_at_the_threshold_is_clean_and_one_over_is_not(
+    tmp_path: Path,
+) -> None:
+    # Worktree sizes are deliberately the OPPOSITE of the verdicts, so the only
+    # thing that can produce them is the committed size.
+    root = build(tmp_path, {"at.bin": RAW_OVER, "over.bin": b"tiny\n"})
+    verdict = grade_with_facts(root, {"at.bin": AT_THRESHOLD, "over.bin": OVER_THRESHOLD})
+    assert [finding.path for finding in verdict.findings] == ["over.bin"]
+    assert verdict.findings[0].message == (
+        "over.bin is a 1048577-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_a_path_with_no_committed_size_is_graded_by_its_worktree_beside_one_that_has_one(
+    tmp_path: Path,
+) -> None:
+    # `smudged.webm` has a fact (a pointer) and is clean; `new.png` is untracked
+    # (no fact) and big, so it is graded exactly as before. One fact existing for
+    # another path changes nothing about it.
+    root = build(
+        tmp_path,
+        {"smudged.webm": b"\0" * SMUDGED, "new.png": RAW_OVER},
+        gitattributes=LFS_ATTRIBUTES,
+    )
+    verdict = grade_with_facts(root, {"smudged.webm": POINTER_SIZE})
+    assert [finding.path for finding in verdict.findings] == ["new.png"]
+    assert verdict.findings[0].message == (
+        "new.png is a 1048577-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_a_path_with_a_committed_size_is_graded_even_when_its_worktree_file_is_gone(
+    tmp_path: Path,
+) -> None:
+    # In the index but deleted on disk (an unstaged deletion): the blob is still
+    # stored, so it is still a large blob outside the LFS filter. Without a fact,
+    # an absent worktree file is skipped, as before.
+    root = build(tmp_path, {"keep.txt": b"x\n"})
+    files = ("keep.txt", "gone.png")
+    stored = runner.run(ROW, root, files, committed_sizes={"gone.png": 2_000_000})
+    assert [finding.path for finding in stored.findings] == ["gone.png"]
+    unknown = runner.run(ROW, root, files, committed_sizes={})
+    assert unknown.outcome is Outcome.CLEAN, unknown.render()
+
+
+# ------------------------------------------------- the shrink-only ratchet register
+#
+# The repository's own register of KNOWN large blobs, `<compliance>/ratchets/
+# LFS-001-large-blobs.yaml`: `over_limit_baseline` maps a repository-relative path
+# to the size in bytes it had when its debt was recorded. It only ever ADDS an
+# allowance (a widening input), so no register means nothing is ratcheted.
+#
+#   LFS-002  over the threshold with no entry (as before)
+#   LFS-003  over its own recorded entry -- names both sizes
+#   LFS-004  an entry that is no longer required, so the register only shrinks
+#
+# `Context` carries no "exhaustive" fact and `core/` is not this gate's to change,
+# so LFS-004 is not gated on the run being whole-tree. It never infers staleness
+# from a path being ABSENT FROM THE SET; it probes each entry's own path exactly
+# the way the set's paths are graded. See check.py's docstring.
+
+REGISTER_NAME = "LFS-001-large-blobs.yaml"
+REGISTER_PATH = f"{fixture_trees()['compliance']}/ratchets/{REGISTER_NAME}"
+RECORDED = 2_000_000
+BIG = b"\0" * RECORDED
+
+
+def register_body(entries: Mapping[str, int] | None = None, *, version: int = 1) -> str:
+    lines = [f"schema_version: {version}"]
+    if not entries:
+        lines.append("over_limit_baseline: {}")
+    else:
+        lines.append("over_limit_baseline:")
+        lines.extend(f'  "{path}": {size}' for path, size in entries.items())
+    return "\n".join(lines) + "\n"
+
+
+def write_register(root: Path, body: str) -> None:
+    target = root / REGISTER_PATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(body)
+
+
+def ratcheted(
+    tmp_path: Path,
+    files: Mapping[str, bytes],
+    entries: Mapping[str, int],
+    gitattributes: str | None = None,
+) -> Path:
+    root = build(tmp_path, {}, gitattributes=gitattributes)
+    for rel, content in files.items():
+        (root / rel).write_bytes(content)
+    write_register(root, register_body(entries))
+    return root
+
+
+def grade_register(
+    root: Path,
+    *,
+    files: Sequence[str] | None = None,
+    committed_sizes: Mapping[str, int] | None = None,
+    exhaustive: bool = False,
+) -> Verdict:
+    given = tuple(files) if files is not None else corpus_files(root)
+    return runner.run(ROW, root, given, exhaustive=exhaustive, committed_sizes=committed_sizes)
+
+
+def test_a_ratcheted_blob_at_its_recorded_size_is_clean(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED})
+    assert (root / "photo.png").stat().st_size == RECORDED > Integrity.THRESHOLD
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+def test_a_ratcheted_blob_that_shrank_but_is_still_over_the_limit_is_clean(tmp_path: Path) -> None:
+    smaller = b"\0" * (RECORDED - 1000)
+    root = ratcheted(tmp_path, {"photo.png": smaller}, {"photo.png": RECORDED})
+    assert Integrity.THRESHOLD < (root / "photo.png").stat().st_size < RECORDED
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_ratcheted_blob_that_grew_is_reported_naming_both_sizes(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"photo.png": b"\0" * (RECORDED + 1)}, {"photo.png": RECORDED})
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.rules == ["LFS-003"]
+    finding = verdict.findings[0]
+    assert finding.path == "photo.png"
+    assert str(RECORDED + 1) in finding.message and str(RECORDED) in finding.message
+    assert finding.message == (
+        f"photo.png is a {RECORDED + 1}-byte blob entering Git without the LFS filter, "
+        f"over its ratchet entry of {RECORDED} bytes"
+    )
+    # The register only shrinks, so the repair never offers to raise the entry.
+    assert finding.fix == (
+        f"shrink photo.png to at most {RECORDED} bytes, or move it to LFS (add a "
+        ".gitattributes rule matching photo.png to filter=lfs, run 'git lfs track' for "
+        "that pattern, then re-add photo.png); the register only shrinks, so do not raise "
+        "its entry"
+    )
+
+
+def test_a_ratcheted_tracked_blob_is_graded_by_its_committed_size_not_the_worktree(
+    tmp_path: Path,
+) -> None:
+    # Worktree is 7 bytes, Git stores RECORDED: at the entry -> clean. One more
+    # stored byte -> LFS-003 naming the STORED size, not the 7 bytes on disk.
+    root = ratcheted(tmp_path, {"photo.png": b"shrunk\n"}, {"photo.png": RECORDED})
+    at = grade_register(root, committed_sizes={"photo.png": RECORDED})
+    assert at.outcome is Outcome.CLEAN, at.render()
+    over = grade_register(root, committed_sizes={"photo.png": RECORDED + 1})
+    assert over.rules == ["LFS-003"], over.render()
+    assert str(RECORDED + 1) in over.findings[0].message
+
+
+def test_an_unratcheted_blob_is_still_reported_beside_a_ratcheted_one(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"known.png": BIG, "new.png": BIG}, {"known.png": RECORDED})
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "new.png")]
+    assert verdict.findings[0].message == (
+        f"new.png is a {RECORDED}-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_an_entry_does_not_excuse_a_different_path(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"other.png": BIG}, {"known.png": RECORDED})
+    verdict = grade_register(root)
+    assert ("LFS-002", "other.png") in [(f.rule, f.path) for f in verdict.findings]
+
+
+# ------------------------------------------------------ stale entries (LFS-004)
+
+
+def test_an_entry_for_a_file_now_at_the_threshold_is_stale(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"photo.png": RAW_AT}, {"photo.png": RECORDED})
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.rules == ["LFS-004"]
+    finding = verdict.findings[0]
+    assert finding.path == "photo.png"
+    assert finding.message == (
+        "ratchet entry for photo.png is no longer required: it is 1048576 bytes, "
+        "at or under the 1048576-byte threshold"
+    )
+    assert finding.fix == f"delete photo.png from over_limit_baseline in {REGISTER_PATH}"
+
+
+def test_an_entry_for_a_file_that_is_gone_is_stale(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"keep.txt": b"x\n"}, {"gone.png": RECORDED})
+    verdict = grade_register(root)
+    assert verdict.rules == ["LFS-004"], verdict.render()
+    assert verdict.findings[0].path == "gone.png"
+    assert verdict.findings[0].message == (
+        "ratchet entry for gone.png is no longer required: it is not a file in the tree"
+    )
+
+
+def test_an_entry_for_a_file_git_now_stores_as_a_pointer_is_stale(tmp_path: Path) -> None:
+    # Moved to LFS: Git stores the ~132-byte pointer while the worktree holds the
+    # smudged full file, so the worktree size would wrongly keep the entry alive.
+    root = ratcheted(
+        tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED}, gitattributes="*.png filter=lfs\n"
+    )
+    verdict = grade_register(root, committed_sizes={"photo.png": POINTER_SIZE})
+    assert verdict.rules == ["LFS-004"], verdict.render()
+    assert verdict.findings[0].message == (
+        "ratchet entry for photo.png is no longer required: Git stores 132 bytes for it, "
+        "at or under the 1048576-byte threshold"
+    )
+
+
+def test_an_entry_for_a_pointer_shaped_file_under_a_matching_rule_is_stale(
+    tmp_path: Path,
+) -> None:
+    root = ratcheted(
+        tmp_path,
+        {"large file.bin": POINTER_HEADER_OVER},
+        {"large file.bin": OVER_THRESHOLD},
+        gitattributes=LFS_ATTRIBUTES,
+    )
+    expect_pointer_header_over_threshold(root, "large file.bin")
+    verdict = grade_register(root)
+    assert verdict.rules == ["LFS-004"], verdict.render()
+    assert verdict.findings[0].message == (
+        "ratchet entry for large file.bin is no longer required: "
+        "it is an LFS pointer under a matching .gitattributes rule"
+    )
+
+
+def test_a_ratcheted_blob_and_its_stale_neighbour_are_told_apart(tmp_path: Path) -> None:
+    root = ratcheted(
+        tmp_path,
+        {"live.png": BIG, "small.png": b"tiny\n"},
+        {"live.png": RECORDED, "small.png": RECORDED, "gone.png": RECORDED},
+    )
+    verdict = grade_register(root)
+    assert sorted((f.rule, f.path) for f in verdict.findings) == [
+        ("LFS-004", "gone.png"),
+        ("LFS-004", "small.png"),
+    ]
+
+
+# ---------------- staleness is probed per entry, never inferred from the given set
+
+
+def test_an_entry_whose_file_the_set_does_not_name_but_is_still_big_is_not_stale(
+    tmp_path: Path,
+) -> None:
+    # The false positive a narrower set must not create: `live.png` is simply not
+    # in this partial set, and a gate that read "unseen" as "stale" would report it.
+    root = ratcheted(tmp_path, {"live.png": BIG, "other.txt": b"x\n"}, {"live.png": RECORDED})
+    for exhaustive in (False, True):
+        verdict = grade_register(root, files=("other.txt",), exhaustive=exhaustive)
+        assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_stale_entry_is_found_by_probing_its_path_whether_or_not_the_set_names_it(
+    tmp_path: Path,
+) -> None:
+    # The pair of the case above: `small.png` is no longer required whether the
+    # set lists it or not, and `exhaustive` changes neither answer. `Context`
+    # does not carry that fact, so this pins the behaviour that stands in for it.
+    root = ratcheted(
+        tmp_path, {"small.png": b"tiny\n", "other.txt": b"x\n"}, {"small.png": RECORDED}
+    )
+    for given in (("other.txt",), ("other.txt", "small.png")):
+        for exhaustive in (False, True):
+            verdict = grade_register(root, files=given, exhaustive=exhaustive)
+            assert verdict.rules == ["LFS-004"], (given, exhaustive, verdict.render())
+
+
+# --------------------------------------------- a register that is not usable
+
+
+FIXTURES = Path(__file__).parent / "fixtures"
+MALFORMED = sorted((FIXTURES / "malformed").glob("*.yaml"))
+
+
+def test_the_malformed_fixtures_are_all_there() -> None:
+    # An empty glob would parametrize to zero cases and pass having tested nothing.
+    assert len(MALFORMED) == 22, [path.name for path in MALFORMED]
+
+
+@pytest.mark.parametrize("fixture", MALFORMED, ids=[path.stem for path in MALFORMED])
+def test_a_register_that_exists_but_is_malformed_is_could_not_run(
+    tmp_path: Path, fixture: Path
+) -> None:
+    # Loud and exit 2, never ignored: ignoring it would grade every ratcheted
+    # blob as a fresh violation, or worse, silently drop an entry's allowance.
+    root = build(tmp_path, {"photo.png": BIG})
+    write_register(root, fixture.read_text(encoding="utf-8"))
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert REGISTER_PATH in verdict.message
+    assert "ratchet register" in verdict.message
+
+
+def test_the_committed_valid_register_ratchets_exactly_what_it_names(tmp_path: Path) -> None:
+    # `fixtures/valid.yaml` is a real register: a plain path and a nested path with
+    # a space in it. Files at their recorded sizes are clean; the one that grew is
+    # not, and the entry for the path nobody created is stale.
+    root = build(tmp_path, {"photo.png": b"\0" * 2_000_000})
+    (root / "assets").mkdir()
+    (root / "assets" / "large file.bin").write_bytes(b"\0" * 1_500_001)
+    write_register(root, (FIXTURES / "valid.yaml").read_text(encoding="utf-8"))
+    verdict = grade_register(root)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-003", "assets/large file.bin")]
+    (root / "assets" / "large file.bin").write_bytes(b"\0" * 1_500_000)
+    clean = grade_register(root)
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+    (root / "photo.png").unlink()
+    gone = grade_register(root)
+    assert [(f.rule, f.path) for f in gone.findings] == [("LFS-004", "photo.png")]
+
+
+def test_a_register_path_that_is_a_directory_is_could_not_run(tmp_path: Path) -> None:
+    root = build(tmp_path, {"photo.png": BIG})
+    (root / REGISTER_PATH).mkdir(parents=True)
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "ratchet register" in verdict.message
+
+
+def test_a_duplicate_path_is_refused_even_when_the_last_value_would_have_passed(
+    tmp_path: Path,
+) -> None:
+    # PyYAML keeps the LAST of a repeated key. "Lowering" an entry by adding a
+    # second line while leaving the old, higher one in place would then be ignored
+    # without a word, so a repeated path is a malformed register.
+    root = build(tmp_path, {"photo.png": BIG})
+    write_register(
+        root,
+        f'schema_version: 1\nover_limit_baseline:\n  "photo.png": {RECORDED - 1}\n'
+        f'  "photo.png": {RECORDED}\n',
+    )
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "photo.png" in verdict.message
+
+
+# ------------------------------------------------ no register: grading as before
+
+
+def test_an_absent_register_grades_exactly_as_before(tmp_path: Path) -> None:
+    root = build(tmp_path, {"photo.png": BIG})
+    assert not (root / REGISTER_PATH).exists()
+    verdict = grade_register(root)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
+    assert verdict.findings[0].message == (
+        f"photo.png is a {RECORDED}-byte blob entering Git without the LFS filter"
+    )
+
+
+def test_an_empty_baseline_grades_exactly_as_before(tmp_path: Path) -> None:
+    root = ratcheted(tmp_path, {"photo.png": BIG}, {})
+    verdict = grade_register(root)
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
+
+
+def test_a_register_whose_tree_the_repository_did_not_declare_is_dropped_not_fatal(
+    tmp_path: Path,
+) -> None:
+    # `resolve_inputs`' widening branch (runner.py): the effective map knows the
+    # tree but the repository's OWN declarations do not. The register is never
+    # read, a widening input grades STRICTER when absent, and the file its entry
+    # would have excused is reported as before.
+    root = ratcheted(tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED})
+    verdict = runner.run(ROW, root, corpus_files(root), declared_trees={})
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
+
+
+def test_a_compliance_tree_declared_absent_drops_the_register(tmp_path: Path) -> None:
+    # `compliance = ""` is the documented way to say "this repository has no such
+    # tree" (`policy.config.absent`): the input is skipped, so a repository with no
+    # compliance tree keeps grading LFS-001 exactly as before.
+    root = ratcheted(tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED})
+    trees = {**fixture_trees(), "compliance": ""}
+    verdict = runner.run(ROW, root, corpus_files(root), trees=trees, declared_trees=trees)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
+
+
+def test_a_compliance_tree_missing_from_the_map_is_could_not_run_naming_what_to_declare(
+    tmp_path: Path,
+) -> None:
+    # PINS A GAP, not a goal. `resolve_inputs` expands every declared input before
+    # it reaches the widening branch, so a tree ABSENT from the map (neither a path
+    # nor "") is could-not-run even for a widening input -- reproduced through the
+    # real CLI on enact-combined with no `--tree compliance=...`. The message names
+    # exactly what to declare, and both repositories in this estate declare it. The
+    # fix is in `runner.resolve_inputs`, not in this check; this test flips with it.
+    root = ratcheted(tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED})
+    trees = {name: path for name, path in fixture_trees().items() if name != "compliance"}
+    verdict = runner.run(ROW, root, corpus_files(root), trees=trees, declared_trees=trees)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "[controls.compliance.trees].compliance" in verdict.message
+
+
+# --------------------------------------------------------- the register's shape
+
+
+def test_the_register_is_a_widening_consumer_input() -> None:
+    assert Integrity.inputs == {"register": f"<compliance>/ratchets/{REGISTER_NAME}"}
+    assert "register" in Integrity.widening_inputs
+    assert "register" not in Integrity.resources
+
+
+def test_editing_the_register_selects_the_gate() -> None:
+    # No `<compliance>` scope entry is needed (and one would make the row
+    # could-not-run in a repository that declares no such tree): `**` already
+    # selects the register, so a commit that edits it is graded.
+    assert scope.intersect(ROW.engine.scope, [REGISTER_PATH]) == (REGISTER_PATH,)
+
+
+def test_the_new_finding_ids_are_distinct_and_collide_with_no_row() -> None:
+    ids = {Integrity.rule, Integrity.GREW, Integrity.STALE}
+    assert ids == {"LFS-002", "LFS-003", "LFS-004"}
+    assert not ids & {row.id for row in load().rows}