From 8f3a42e9ffa448510f83972c024dc95063180e2d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 08:19:58 +0000 Subject: [PATCH] cbz_drift: reviewed LEAN-DRIFT exemptions keyed by exact location set federation-drift has been red on every main PR since Math-#514 merged. Its reused copy of CapFirstExit.frontier_image_subset opens Set where the original opens Set unitInterval, and the crawler counts open as part of a declaration's interface on purpose. The statement uses no unitInterval name, so the difference is inert. This is option (b) from the FEDDRIFT-C88-FIX proposal (main#738 6568753056, picked at 6569726362). tools/cbz_drift/reviewed_exemptions.json lists accepted drifts. An entry names one declaration and the complete set of its locations (repository, path, SHA-256 of the interface the crawl computes). A drift is exempt, INFO LEAN-EXEMPT, only when its location set equals an entry's exactly; any interface change or a new or removed location blocks again, and an entry that matches nothing is INFO EXEMPT-UNUSED. A malformed file is a BLOCK. The file lives with the tool, not in a crawled repository. Comments, whitespace and proof bodies are outside the interface, so edits to those keep the exemption (wording per main#738 6570035707). Seven tests cover exact match, interface change, proof and comment edits, a new location, a wrong name, malformed documents and the shipped file. Four mutants (name-only match, path-only key, silent malformed file, no unused report) each fail them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01S16677s1SGeAJmN3QMz4ip --- tests/test_cbz_drift.py | 77 ++++++++++++++++++++++ tools/cbz_drift/crawl.py | 82 ++++++++++++++++++++++-- tools/cbz_drift/reviewed_exemptions.json | 22 +++++++ 3 files changed, 174 insertions(+), 7 deletions(-) create mode 100644 tools/cbz_drift/reviewed_exemptions.json diff --git a/tests/test_cbz_drift.py b/tests/test_cbz_drift.py index b54825d67..3a7dc219b 100644 --- a/tests/test_cbz_drift.py +++ b/tests/test_cbz_drift.py @@ -267,6 +267,83 @@ def test_tips_mode_reads_default_tips(self): self.assertEqual(codes(self.fed.crawl(at='tips'), 'BLOCK'), ['LEAN-DRIFT']) +class ExemptionTests(FedCase): + """Reviewed LEAN-DRIFT exemptions match the complete location set by interface hash.""" + + STALE = LEAN_A.replace('n + 0 = n', '0 + n = n') + + def drifted(self): + self.fed.build(b_lean=self.STALE) + rep = self.fed.crawl() + return [f for f in rep['findings'] if f['code'] == 'LEAN-DRIFT'][0] + + @staticmethod + def doc(f, **kw): + locs = [] + for v in f['variants']: + for loc in v['locations']: + repo, rest = loc.split('@', 1) + locs.append({'repository': repo, 'path': rest.split(':', 1)[1].rsplit(':', 1)[0], + 'interface_sha256': v['interface_sha256']}) + ent = dict({'id': 'T-01', 'name': f['name'], 'rationale': 'reviewed in a test', 'locations': locs}, **kw) + return {'schema': crawl.EXEMPTIONS_SCHEMA, 'exemptions': [ent]} + + def test_exact_exemption_turns_the_drift_into_info(self): + doc = self.doc(self.drifted()) + rep = self.fed.crawl(exemptions=doc) + self.assertEqual(codes(rep, 'BLOCK'), []) + self.assertEqual([f['exemption'] for f in rep['findings'] if f['code'] == 'LEAN-EXEMPT'], ['T-01']) + self.assertNotIn('EXEMPT-UNUSED', codes(rep, 'INFO')) + + def test_changed_interface_blocks_again_and_reports_the_entry_unused(self): + doc = self.doc(self.drifted()) + self.fed.pins['b'] = self.fed.commit('b', {'Copy/A.lean': LEAN_A.replace('n + 0 = n', 'n = n + 0')}) + self.fed.write_seed() + rep = self.fed.crawl(exemptions=doc) + self.assertEqual(codes(rep, 'BLOCK'), ['LEAN-DRIFT']) + self.assertIn('EXEMPT-UNUSED', codes(rep, 'INFO')) + + def test_proof_and_comment_edits_stay_exempt(self): + doc = self.doc(self.drifted()) + edited = self.STALE.replace(':= by simp', ':= by\n omega -- another proof').replace('/-- doc -/', '/-- edited -/') + self.fed.pins['b'] = self.fed.commit('b', {'Copy/A.lean': edited}) + self.fed.write_seed() + rep = self.fed.crawl(exemptions=doc) + self.assertEqual(codes(rep, 'BLOCK'), []) + self.assertIn('LEAN-EXEMPT', codes(rep, 'INFO')) + + def test_a_new_location_blocks_again(self): + doc = self.doc(self.drifted()) + self.fed.pins['b'] = self.fed.commit('b', {'Copy2/A.lean': self.STALE}) + self.fed.write_seed() + self.assertEqual(codes(self.fed.crawl(exemptions=doc), 'BLOCK'), ['LEAN-DRIFT']) + + def test_an_entry_for_another_name_does_not_exempt(self): + doc = self.doc(self.drifted()) + doc['exemptions'][0]['name'] = 'Fed.f' + rep = self.fed.crawl(exemptions=doc) + self.assertEqual(codes(rep, 'BLOCK'), ['LEAN-DRIFT']) + self.assertIn('EXEMPT-UNUSED', codes(rep, 'INFO')) + + def test_malformed_exemptions_block(self): + f = self.drifted() + one = self.doc(f) + one['exemptions'][0]['locations'] = one['exemptions'][0]['locations'][:1] + bad_hash = self.doc(f) + bad_hash['exemptions'][0]['locations'][0]['interface_sha256'] = 'x' * 64 + for doc in ({'schema': 'other', 'exemptions': []}, {'error': 'not json'}, one, bad_hash): + rep = self.fed.crawl(exemptions=doc) + self.assertIn('MALFORMED', codes(rep, 'BLOCK'), doc) + self.assertIn('LEAN-DRIFT', codes(rep, 'BLOCK'), doc) + + def test_shipped_exemptions_file_is_valid(self): + doc = crawl.load_exemptions(crawl.DEFAULT_EXEMPTIONS) + c = crawl.Crawl({}, exemptions=doc) + self.assertEqual(c.exemption_errors, []) + self.assertTrue(c.exemptions) + self.assertTrue(all(len(e['key']) >= 2 for e in c.exemptions)) + + class PinTests(FedCase): def test_gitlink_disagreeing_with_pins_blocks(self): self.fed.build() diff --git a/tools/cbz_drift/crawl.py b/tools/cbz_drift/crawl.py index cf47050a9..2710032ba 100644 --- a/tools/cbz_drift/crawl.py +++ b/tools/cbz_drift/crawl.py @@ -32,6 +32,9 @@ LEAN-SYNTAX a Lean file could not be lexed or its scopes do not balance BLOCK LEAN-EVIDENCE Lean files under an evidence directory are frozen copies, not INFO compared (sealed checker inputs, snapshots, mutation controls) + LEAN-EXEMPT a LEAN-DRIFT matched a reviewed exemption exactly (every INFO + location's repository, path and interface SHA-256) + EXEMPT-UNUSED a reviewed exemption matched no drift this run (it is stale) INFO LAKE-DEP a lake dependency on a crawled repository pins another rev INFO PIN-DIVERGENT two reached repositories pin one repository differently INFO FETCH-FAILED --fetch could not refresh a repository, so its tips are not current BLOCK @@ -47,6 +50,15 @@ (`--at tips`), and `--override NAME=REV` replaces one repository's ref (to test a candidate head against the rest of the federation). +Reviewed exemptions. `reviewed_exemptions.json` beside this file (or `--exemptions FILE`) +lists LEAN-DRIFT findings that a review has accepted. An entry names one declaration and +the complete set of its locations, each as repository, path and the SHA-256 of the +interface the crawl computes there. A drift is exempt only when its location set equals an +entry's exactly; any change to either interface, or a new or removed location, blocks +again. Comments, whitespace and proof bodies are outside the interface, so they do not. +A malformed exemptions file is a BLOCK. The list lives with the tool, not in a crawled +repository, so a crawled repository cannot exempt itself. + Standard library only. Exit: 0 no BLOCK, 1 BLOCK findings, 2 usage or internal error. """ from __future__ import annotations @@ -65,6 +77,8 @@ import lean_decls # noqa: E402 BLOCK, INFO = 'BLOCK', 'INFO' +EXEMPTIONS_SCHEMA = 'cbz.drift.exemptions.v1' +DEFAULT_EXEMPTIONS = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'reviewed_exemptions.json') # A path segment named `evidence` or ending in `-evidence` (cbz/evidence//, kernel/cbz-evidence/, # formal-evidence/) holds frozen copies: sealed checker inputs, snapshots of earlier commits and mutation # controls. They are deliberately different from the live sources, so they are not compared. @@ -196,8 +210,9 @@ def parse_gitmodules(text): class Crawl: - def __init__(self, local, at='pins', overrides=None, fetch=False, clone_into=None): + def __init__(self, local, at='pins', overrides=None, fetch=False, clone_into=None, exemptions=None): self.local, self.at, self.overrides, self.fetch = local, at, dict(overrides or {}), fetch + self.exemptions = self.parse_exemptions(exemptions) self.clone_into, self.urls = clone_into, {} self.findings, self.repos, self.refs = [], {}, {} self.pins, self.optional, self.edges = {}, set(), [] @@ -208,6 +223,33 @@ def __init__(self, local, at='pins', overrides=None, fetch=False, clone_into=Non def add(self, level, code, msg, **where): self.findings.append(dict(where, level=level, code=code, message=msg)) + def parse_exemptions(self, doc): + """Validate a reviewed-exemptions document; None means no exemptions.""" + self.exemption_errors = [] + if doc is None: + return [] + entries = doc.get('exemptions') if isinstance(doc, dict) else None + if not isinstance(entries, list) or doc.get('schema') != EXEMPTIONS_SCHEMA: + self.exemption_errors.append('exemptions document is not %s with an exemptions list' % EXEMPTIONS_SCHEMA) + return [] + out, seen = [], set() + for ent in entries: + locs = ent.get('locations') if isinstance(ent, dict) else None + ok = (isinstance(ent, dict) and all(isinstance(ent.get(k), str) and ent.get(k) for k in ('id', 'name', 'rationale')) + and isinstance(locs, list) and len(locs) >= 2 + and all(isinstance(l, dict) and isinstance(l.get('repository'), str) and isinstance(l.get('path'), str) + and re.fullmatch(r'[0-9a-f]{64}', str(l.get('interface_sha256', ''))) for l in locs)) + if not ok or ent['id'] in seen: + self.exemption_errors.append('exemption %r is malformed or duplicated' % (ent.get('id') if isinstance(ent, dict) else ent)) + continue + seen.add(ent['id']) + key = frozenset((repo_key(l['repository']), l['path'], l['interface_sha256']) for l in locs) + if len(key) != len(locs): + self.exemption_errors.append('exemption %r lists a location twice' % ent['id']) + continue + out.append(dict(id=ent['id'], name=ent['name'], key=key, used=False)) + return out + def open(self, key, why): if key in self.repos: return self.repos[key] @@ -628,10 +670,26 @@ def check_lean(self): for l in locs: variants.setdefault((l['kind'], l['interface']), []).append(l) if len(variants) > 1: - self.add(BLOCK, 'LEAN-DRIFT', '%s has %d different interfaces across %d locations' % (name, len(variants), len(locs)), - name=name, variants=[{'kind': k, 'interface': i, 'locations': ['%s@%s:%s:%d' % ( - l['repo'], l['ref'][:12], l['path'], l['line']) for l in ls]} for (k, i), ls in variants.items()]) + key = frozenset((l['repo'], l['path'], hashlib.sha256(l['interface'].encode('utf-8')).hexdigest()) for l in locs) + ex = next((e for e in self.exemptions if e['name'] == name and e['key'] == key), None) + detail = [{'kind': k, 'interface': i, 'interface_sha256': hashlib.sha256(i.encode('utf-8')).hexdigest(), + 'locations': ['%s@%s:%s:%d' % (l['repo'], l['ref'][:12], l['path'], l['line']) for l in ls]} + for (k, i), ls in variants.items()] + if ex is not None: + ex['used'] = True + self.add(INFO, 'LEAN-EXEMPT', '%s has %d different interfaces across %d locations; reviewed exemption %s matches ' + 'every location exactly' % (name, len(variants), len(locs), ex['id']), name=name, exemption=ex['id'], + variants=detail) + else: + self.add(BLOCK, 'LEAN-DRIFT', '%s has %d different interfaces across %d locations' % (name, len(variants), len(locs)), + name=name, variants=detail) self.stats['lean_shared_names'] = shared + for msg in self.exemption_errors: + self.add(BLOCK, 'MALFORMED', msg, path='reviewed_exemptions.json') + for e in self.exemptions: + if not e['used']: + self.add(INFO, 'EXEMPT-UNUSED', 'reviewed exemption %s (%s) matched no drift; remove it if the copies now agree' + % (e['id'], e['name']), exemption=e['id']) for (a, b) in sorted({tuple(sorted((x, y))) for x, ys in coupled.items() for y in ys}): if packages.get(a) != packages.get(b): self.add(INFO, 'TOOLCHAIN', 'packages %s:%s and %s:%s share declarations but use %s and %s' % ( @@ -651,9 +709,17 @@ def report(self): } -def run(seed, search, at='pins', seed_ref=None, overrides=None, fetch=False, clone_into=None): +def load_exemptions(path): + """Read a reviewed-exemptions file; an unreadable or non-JSON file is returned as a document that fails validation.""" + try: + return json.loads(pathlib.Path(path).read_text(encoding='utf-8')) + except (OSError, ValueError) as exc: + return {'error': str(exc)} + + +def run(seed, search, at='pins', seed_ref=None, overrides=None, fetch=False, clone_into=None, exemptions=None): local = find_local_repos(search) - c = Crawl(local, at=at, overrides=overrides, fetch=fetch, clone_into=clone_into) + c = Crawl(local, at=at, overrides=overrides, fetch=fetch, clone_into=clone_into, exemptions=exemptions) c.seed(repo_key(seed) if '/' in seed else _match_name(seed, local), seed_ref) c.close_graph() c.check_pins() @@ -679,6 +745,8 @@ def main(argv=None): ap.add_argument('--fetch', action='store_true', help='git fetch commits missing locally') ap.add_argument('--clone-into', metavar='DIR', help='clone discovered repositories that no --search directory holds') ap.add_argument('--json', metavar='FILE', help='write the full report here') + ap.add_argument('--exemptions', metavar='FILE', default=DEFAULT_EXEMPTIONS, + help='reviewed LEAN-DRIFT exemptions (default: reviewed_exemptions.json beside this file)') args = ap.parse_args(argv) try: ov = {} @@ -690,7 +758,7 @@ def main(argv=None): if args.clone_into: pathlib.Path(args.clone_into).mkdir(parents=True, exist_ok=True) rep = run(args.seed, args.search, at=args.at, seed_ref=args.seed_ref, overrides=ov, fetch=args.fetch, - clone_into=args.clone_into) + clone_into=args.clone_into, exemptions=load_exemptions(args.exemptions)) except CrawlError as exc: print('drift crawler error: %s' % exc, file=sys.stderr) return 2 diff --git a/tools/cbz_drift/reviewed_exemptions.json b/tools/cbz_drift/reviewed_exemptions.json new file mode 100644 index 000000000..81feb2ed4 --- /dev/null +++ b/tools/cbz_drift/reviewed_exemptions.json @@ -0,0 +1,22 @@ +{ + "schema": "cbz.drift.exemptions.v1", + "exemptions": [ + { + "id": "FEDDRIFT-C88-01", + "name": "CapFirstExit.frontier_image_subset", + "rationale": "Math-#514 added a reused copy of this theorem whose context opens Set where the original opens Set unitInterval; the copy's single topology import does not provide unitInterval. The statement uses no name from the unitInterval namespace (no scoped I, no sigma, no unitInterval.* identifier), checked against the interface the crawl records at both locations, so the context difference does not change it. Only a change to either interface (the statement or its context: open, variable and the like) re-blocks; comments, whitespace and proof bodies are outside interface_sha256. Remove this entry if the #514 packet owner restores the original context in the copy. Routed at main#738 comments 6568570507 and 6569726362; design 6568753056; wording 6570035707.", + "locations": [ + { + "repository": "d6g8k5htny-coder/Math-", + "path": "frontiers/cap_first_exit_lean_20261002/CapFirstExit.lean", + "interface_sha256": "d0b4c10808199ba143e93ceb53999b618a000f7fc8b45b98720b605e0dc8c317" + }, + { + "repository": "d6g8k5htny-coder/Math-", + "path": "frontiers/source_derivative_gaussian_20261025/inputs/elder/ReusedCompactFrontier.lean", + "interface_sha256": "460289c21db481a8af33b1910b066f50100fd64c2a5c9798318eed7522e4519c" + } + ] + } + ] +}