Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Accept existing covering proofs in the completion guard
rcourtmancfd1477852ac
diff --git a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.mdindex 45ee2cf79b..1833795b7e 100644--- a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md+++ b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md@@ -606,7 +606,8 @@ must include:1. the matching subsystem contract update2. any dependent subsystem contract whose `Canonical Files`, `Shared Boundaries`, or `Extension Points` explicitly reference a touched runtime path-3. at least one matching verification artifact update+3. a matching verification artifact: a registered proof that already exercises+ each touched runtime file, or a staged update to oneA staged contract file only counts when its diff changes a substantive contractsection. Update the owning statement of current behavior, responsibility, shared@@ -643,6 +644,18 @@ test elsewhere in the same subsystem is never proof on its own: the registryaudit keeps `allow_same_subsystem_tests` false, because it would accept anytest the subsystem owns rather than the ones a path policy names.+A registered proof counts without being edited when it already exercises the+touched runtime file in the tree being judged (the index before a commit, the+commit itself in CI): a Go test compiled with or importing the file's package,+a TypeScript or JavaScript test importing the module, a Python test importing+it, or, for docs, workflows, scripts and data files, a test naming the file's+path. Reading a code file's source as text (`readFileSync`, Vite `?raw`) is+not coverage, and a type-only import does not run the module. CI's test jobs+run the proof, so an existing covering test is the verification. Only a change+no registered proof exercises needs a staged proof, so do not add a source-text+assertion to a proof file to satisfy the guard; make a proof import and test+the file instead. `subsystem_lookup.py --pretty` names the covering proofs.+For changes to a declared contract, cross-subsystem dependencies are notadvisory. If a touched runtime path is named in another subsystem contract's`Canonical Files`, `Shared Boundaries`, or `Extension Points`, include thediff --git a/scripts/release_control/canonical_completion_guard.py b/scripts/release_control/canonical_completion_guard.pyindex 71b6eaeade..7b4d207e77 100644--- a/scripts/release_control/canonical_completion_guard.py+++ b/scripts/release_control/canonical_completion_guard.py@@ -2,8 +2,9 @@"""Canonical subsystem completion guard.Blocks commits when staged runtime changes touch a canonical subsystem but the-matching subsystem contract file and required verification artifact are not-staged in the same commit.+matching subsystem contract file is not staged in the same commit, or when no+registered proof verifies the change: a proof counts when it is staged or when+it already exercises each touched runtime file (see proof_coverage.py)."""from __future__ import annotations@@ -20,6 +21,7 @@ from typing import Dict, List, Sequence, Setimport browser_verification_guardfrom control_plane import DEFAULT_CONTROL_PLANE+import proof_coveragefrom repo_file_io import git_env, load_repo_json, merged_in_pathsfrom subsystem_contracts import load_contract_index, referenced_contracts_for_path@@ -484,6 +486,81 @@ def staged_verification_files_for_requirement(rule: dict, requirement: dict, stareturn sorted(set(matches))+def candidate_proof_files(requirement: dict, *, revision: str | None) -> List[str]:+ """Registered proofs for a requirement as they exist in the evaluated tree."""+ candidates = set(requirement.get("exact_files", []))+ test_prefixes = list(requirement.get("test_prefixes", []))+ if test_prefixes:+ candidates.update(+ path+ for path in proof_coverage.git_tracked_paths(revision, test_prefixes, repo_root=REPO_ROOT)+ if is_test_or_fixture(path)+ )+ return sorted(candidates)+++def uncovered_runtime_files_for_requirement(+ requirement: dict,+ read: proof_coverage.TextReader,+ *,+ revision: str | None,+) -> List[str]:+ """Touched runtime files that no existing registered proof exercises.++ A registered proof that already imports (or compiles with) the touched file+ and runs in CI verifies the change without being edited, so the guard no+ longer asks for a staged diff to it. Requiring that diff is what turned+ proof files into piles of source-text pins.+ """+ if requirement.get("path_policy_gap"):+ return list(requirement.get("touched_runtime_files", []))+ candidates = candidate_proof_files(requirement, revision=revision)+ return [+ path+ for path in requirement.get("touched_runtime_files", [])+ if not proof_coverage.covering_proof_files(path, candidates, read)+ ]+++def missing_verification_requirements(+ impacted: Dict[str, dict],+ staged_files: Sequence[str],+ *,+ revision: str | None = None,+ read: proof_coverage.TextReader | None = None,+) -> Dict[str, dict]:+ """Requirements met neither by a staged proof nor by an existing covering proof.++ `revision` selects the tree the proofs are read from: the index when None+ (a commit being made), the evaluated commit otherwise (CI and pre-push).+ """+ owned_reader = proof_coverage.GitTextReader(revision, repo_root=REPO_ROOT) if read is None else None+ reader = read or owned_reader+ missing_verification: Dict[str, dict] = {}+ try:+ for subsystem_id, data in impacted.items():+ missing_requirements: List[dict] = []+ for requirement in data.get("verification_requirements", []):+ if staged_verification_files_for_requirement(data, requirement, staged_files):+ continue+ uncovered = uncovered_runtime_files_for_requirement(+ requirement, reader, revision=revision+ )+ if uncovered:+ missing_requirements.append(+ {**requirement, "uncovered_runtime_files": uncovered}+ )+ if missing_requirements:+ missing_verification[subsystem_id] = {+ **data,+ "missing_requirements": missing_requirements,+ }+ finally:+ if owned_reader is not None:+ owned_reader.close()+ return missing_verification++def git_blob_text(spec: str) -> str:result = subprocess.run(["git", "show", spec],@@ -657,6 +734,14 @@ def format_missing_requirements(exact_files = sorted(requirement.get("exact_files", []))test_prefixes = sorted(requirement.get("test_prefixes", []))allow_same_subsystem_tests = bool(requirement.get("allow_same_subsystem_tests", False))+ uncovered = sorted(requirement.get("uncovered_runtime_files", []))+ if uncovered:+ lines.append(" no acceptable proof below already exercises:")+ for path in uncovered:+ lines.append(f" {path}")+ lines.append(+ " make one of them import and test each file (Go: compile with or import its package), or stage a change to one"+ )if exact_files:lines.append(" acceptable exact proof files include:")for path in exact_files:@@ -679,7 +764,8 @@ def format_missing_requirements("A staged contract file only counts if its staged diff changes a substantive contract section,","not just `Contract Metadata` or cosmetic noise.","Each touched runtime path must also satisfy the first matching",- "verification policy from that subsystem's registry entry.",+ "verification policy from that subsystem's registry entry: an acceptable",+ "proof that already exercises the path counts unchanged; otherwise stage one.",])return "\n".join(lines)@@ -721,18 +807,11 @@ def check_staged_contracts(if contract_path in staged_setif not staged_contract_has_substantive_change(contract_path, diff_base, revision)}- missing_verification: Dict[str, dict] = {}- for subsystem_id, data in impacted.items():- missing_requirements = [- requirement- for requirement in data.get("verification_requirements", [])- if not staged_verification_files_for_requirement(data, requirement, staged_files)- ]- if missing_requirements:- missing_verification[subsystem_id] = {- **data,- "missing_requirements": missing_requirements,- }+ missing_verification = missing_verification_requirements(+ impacted,+ staged_files,+ revision=governance_revision,+ )if not missing_contracts and not insufficient_contract_updates and not missing_verification:return 0diff --git a/scripts/release_control/canonical_completion_guard_test.py b/scripts/release_control/canonical_completion_guard_test.pyindex 2c90961cea..5070688688 100644--- a/scripts/release_control/canonical_completion_guard_test.py+++ b/scripts/release_control/canonical_completion_guard_test.py@@ -3,6 +3,7 @@ import canonical_completion_guardimport jsonimport osimport subprocess+import sysimport tempfileimport unittestfrom contextlib import redirect_stderr@@ -31,6 +32,7 @@ from canonical_completion_guard import (stdin_files,subsystem_matches_path,)+from proof_coverage import GitTextReader, proof_covers_runtime_filefrom repo_file_io import canonical_workspace_repos_root, strip_local_git_envWORKSPACE_REPOS_ROOT = canonical_workspace_repos_root(REPO_ROOT)@@ -3136,10 +3138,29 @@ None yet.patch("canonical_completion_guard.load_subsystem_rules", return_value=rules),# Isolate verification routing from contract-edit checks.patch("canonical_completion_guard.required_contract_updates", return_value={}),+ # Route by staged proofs alone: the real proofs already+ # import their runtime files, which would satisfy both+ # policies unchanged (see ExistingProofCoverageTest).+ patch("proof_coverage.covering_proof_files", return_value=[]),redirect_stderr(io.StringIO()),):self.assertEqual(check_staged_contracts(paths), expected)+ def test_recovery_and_transfer_edits_pass_on_existing_covering_proofs(self):+ rules = load_subsystem_rules()+ paths = [+ "frontend-modern/src/components/Settings/RecoverySettingsPanel.tsx",+ "frontend-modern/src/components/Settings/BackupTransferDialogs.tsx",+ "frontend-modern/src/components/Settings/useBackupTransferFlow.ts",+ ]+ with (+ patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}, clear=False),+ patch("canonical_completion_guard.load_subsystem_rules", return_value=rules),+ patch("canonical_completion_guard.required_contract_updates", return_value={}),+ redirect_stderr(io.StringIO()) as stderr,+ ):+ self.assertEqual(check_staged_contracts(paths), 0, stderr.getvalue())+def test_frontend_primitive_remaining_settings_shells_use_specific_guardrails(self):rule = next(rule for rule in load_subsystem_rules() if rule["id"] == "frontend-primitives")runtime_files = [@@ -4575,5 +4596,378 @@ with open(os.environ["PULSE_TEST_GUARD_LOG"], "a", encoding="utf-8") as log:)+class ProofCoverageRelationTest(unittest.TestCase):+ """A registered proof covers a runtime file when it exercises it, not when+ it reads the file's source as text."""++ @staticmethod+ def covers(proof: str, proof_text: str, runtime: str, runtime_text: str = "x\n") -> bool:+ files = {proof: proof_text, runtime: runtime_text}+ return proof_covers_runtime_file(proof, runtime, files.get)++ def test_go_proof_in_the_package_directory_covers(self) -> None:+ self.assertTrue(self.covers("internal/a/b_test.go", "package a_test\n", "internal/a/c.go"))++ def test_go_proof_importing_the_package_covers(self) -> None:+ proof = 'package api\n\nimport (\n\t"github.com/rcourtman/pulse-go-rewrite/internal/a"\n)\n'+ self.assertTrue(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))++ def test_go_proof_elsewhere_without_the_import_does_not_cover(self) -> None:+ proof = 'package api\n\nimport "github.com/rcourtman/pulse-go-rewrite/internal/ab"\n'+ self.assertFalse(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))++ def test_go_non_test_file_does_not_cover(self) -> None:+ self.assertFalse(self.covers("internal/a/b.go", "package a\n", "internal/a/c.go"))++ def test_ts_relative_and_alias_imports_cover(self) -> None:+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"+ relative = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"+ self.assertTrue(self.covers(relative, "import { Widget } from '../Widget';\n", runtime))+ alias = "frontend-modern/src/pages/__tests__/Page.test.tsx"+ self.assertTrue(+ self.covers(alias, "import {\n Widget,\n other,\n} from '@/components/Foo/Widget';\n", runtime)+ )+ self.assertTrue(+ self.covers(alias, "const mod = await import('@/components/Foo/Widget');\n", runtime)+ )++ def test_ts_directory_import_resolves_to_index(self) -> None:+ runtime = "frontend-modern/src/features/foo/index.ts"+ proof = "frontend-modern/src/features/__tests__/foo.test.ts"+ self.assertTrue(self.covers(proof, "import { foo } from '../foo';\n", runtime))++ def test_ts_type_only_import_does_not_cover(self) -> None:+ runtime = "frontend-modern/src/types/widget.ts"+ proof = "frontend-modern/src/components/__tests__/Widget.test.tsx"+ self.assertFalse(+ self.covers(proof, "import type { Widget } from '@/types/widget';\n", runtime)+ )++ def test_ts_source_text_pin_does_not_cover(self) -> None:+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.guardrails.test.ts"+ pin = (+ "import { readFileSync } from 'node:fs';\n"+ "const source = readFileSync('src/components/Foo/Widget.tsx', 'utf8');\n"+ "expect(source).toContain('Widget');\n"+ )+ self.assertFalse(self.covers(proof, pin, runtime))+ raw = "import widgetSource from '@/components/Foo/Widget.tsx?raw';\n"+ self.assertFalse(self.covers(proof, raw, runtime))++ def test_ts_mocked_module_does_not_cover(self) -> None:+ runtime = "frontend-modern/src/api/charts.ts"+ proof = "frontend-modern/src/components/__tests__/Chart.test.tsx"+ text = "vi.mock('@/api/charts', () => ({ ChartsAPI: {} }));\nimport { ChartsAPI } from '@/api/charts';\n"+ self.assertFalse(self.covers(proof, text, runtime))++ def test_ts_mock_with_import_argument_does_not_cover(self) -> None:+ runtime = "frontend-modern/src/api/charts.ts"+ proof = "frontend-modern/src/components/__tests__/Chart.test.tsx"+ self.assertFalse(self.covers(proof, "vi.mock(import('@/api/charts'), () => ({}));\n", runtime))++ def test_ts_comments_and_type_queries_do_not_cover(self) -> None:+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"+ for text in (+ "// const mod = await import('../Widget');\n",+ "/*\nimport { Widget } from '../Widget';\n*/\n",+ "type WidgetModule = typeof import('../Widget');\n",+ ):+ with self.subTest(text=text):+ self.assertFalse(self.covers(proof, text, runtime))++ def test_ts_imports_in_trailing_comments_strings_or_member_calls_do_not_cover(self) -> None:+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"+ for text in (+ "const n = 1; // await import('../Widget');\n",+ "const s = \"import('../Widget')\";\n",+ "loader.require('../Widget');\n",+ ):+ with self.subTest(text=text):+ self.assertFalse(self.covers(proof, text, runtime))++ def test_ts_specifier_resolves_to_one_file(self) -> None:+ proof = "frontend-modern/src/features/__tests__/foo.test.ts"+ files = {+ proof: "import { foo } from '../foo';\n",+ "frontend-modern/src/features/foo.ts": "x",+ "frontend-modern/src/features/foo/index.ts": "x",+ }+ self.assertTrue(proof_covers_runtime_file(proof, "frontend-modern/src/features/foo.ts", files.get))+ self.assertFalse(+ proof_covers_runtime_file(proof, "frontend-modern/src/features/foo/index.ts", files.get)+ )++ def test_go_package_path_outside_import_declarations_does_not_cover(self) -> None:+ proof = (+ "package api\n\n// see github.com/rcourtman/pulse-go-rewrite/internal/a\n"+ 'const sample = "github.com/rcourtman/pulse-go-rewrite/internal/a"\n'+ )+ self.assertFalse(self.covers("internal/api/x_test.go", proof, "internal/a/c.go"))+ aliased = 'package api\n\nimport alpha "github.com/rcourtman/pulse-go-rewrite/internal/a"\n'+ self.assertTrue(self.covers("internal/api/x_test.go", aliased, "internal/a/c.go"))++ def test_go_proof_behind_a_non_platform_build_tag_does_not_cover(self) -> None:+ for constraint, expected in (+ ("//go:build ignore", False),+ ("//go:build integration", False),+ ("//go:build linux && !arm64", True),+ ("//go:build go1.21", True),+ ):+ with self.subTest(constraint=constraint):+ proof = f"{constraint}\n\npackage a\n"+ self.assertEqual(self.covers("internal/a/b_test.go", proof, "internal/a/c.go"), expected)++ def test_python_docstring_and_type_checking_imports_do_not_cover(self) -> None:+ runtime = "scripts/release_control/widget_policy.py"+ proof = "scripts/release_control/widget_policy_test.py"+ docstring = '"""Usage:\nimport widget_policy\n"""\n'+ type_only = "from typing import TYPE_CHECKING\nif TYPE_CHECKING:\n import widget_policy\n"+ self.assertFalse(self.covers(proof, docstring, runtime))+ self.assertFalse(self.covers(proof, type_only, runtime))+ dynamic = "import importlib\nmod = importlib.import_module('widget_policy')\n"+ self.assertTrue(self.covers(proof, dynamic, runtime))++ def test_python_stdlib_name_does_not_cover_a_same_named_file(self) -> None:+ proof = "scripts/tests/test_tool.py"+ if "json" in getattr(sys, "stdlib_module_names", ()):+ self.assertFalse(self.covers(proof, "import json\n", "scripts/json.py"))+ self.assertTrue(self.covers(proof, "import scripts.json\n", "scripts/json.py"))++ def test_python_multiline_and_package_imports(self) -> None:+ runtime = "scripts/release_control/widget_policy.py"+ proof = "scripts/release_control/widget_policy_test.py"+ self.assertTrue(self.covers(proof, "import os\nimport widget_policy\n\nclass T: pass\n", runtime))+ self.assertTrue(self.covers(proof, "from release_control import (\n other,\n widget_policy,\n)\n", runtime))+ self.assertFalse(self.covers(proof, "import os\n# import widget_policy\n", runtime))++ def test_python_proof_importing_the_module_covers(self) -> None:+ runtime = "scripts/release_control/widget_policy.py"+ self.assertTrue(+ self.covers("scripts/tests/test_widget.py", "from widget_policy import check\n", runtime)+ )+ self.assertTrue(+ self.covers("scripts/tests/test_widget.py", "import os, widget_policy\n", runtime)+ )+ self.assertFalse(+ self.covers("scripts/tests/test_widget.py", "import widget_policy_extra\n", runtime)+ )++ def test_non_code_file_is_covered_by_a_proof_that_names_its_path(self) -> None:+ proof = "scripts/release_control/ai_docs_policy_test.py"+ self.assertTrue(self.covers(proof, 'DOC = REPO / "docs/AI.md"\n', "docs/AI.md"))+ self.assertFalse(self.covers(proof, 'DOC = REPO / "docs/API.md"\n', "docs/AI.md"))+ mirror = 'DOC = REPO / "frontend-modern/public/docs/AI.md"\n'+ self.assertFalse(self.covers(proof, mirror, "docs/AI.md"))+ self.assertFalse(self.covers(proof, 'DOC = "docs/AI.md.bak"\n', "docs/AI.md"))++ def test_missing_files_do_not_cover(self) -> None:+ runtime = "frontend-modern/src/components/Foo/Widget.tsx"+ proof = "frontend-modern/src/components/Foo/__tests__/Widget.test.tsx"+ files = {proof: "import { Widget } from '../Widget';\n"}+ self.assertFalse(proof_covers_runtime_file(proof, runtime, files.get))+ self.assertFalse(proof_covers_runtime_file(proof, proof, {proof: "x"}.get))+++class ExistingProofCoverageTest(unittest.TestCase):+ """A commit that changes an owned runtime file passes verification when a+ registered proof already exercises that file, without editing the proof.+ Requiring a staged proof diff is what filled proof files with source-text+ pins. A change no registered proof exercises still needs a staged proof."""++ SUBSYSTEMS = "docs/release-control/v6/internal/subsystems"+ REGISTRY = f"{SUBSYSTEMS}/registry.json"+ CONTRACT = f"{SUBSYSTEMS}/alpha.md"+ GO_RUNTIME = "app/alpha/widget.go"+ GO_PROOF = "app/alpha/widget_test.go"+ GO_UNCOVERED = "app/alpha/sub/gadget.go"+ TS_RUNTIME = "frontend-modern/src/alpha/widget.ts"+ TS_PROOF = "frontend-modern/src/alpha/__tests__/widget.test.ts"+ TS_PINNED = "frontend-modern/src/alpha/pinned.ts"+ TS_PIN_PROOF = "frontend-modern/src/alpha/__tests__/alpha.guardrails.test.ts"++ def setUp(self) -> None:+ temp_dir = tempfile.TemporaryDirectory()+ self.addCleanup(temp_dir.cleanup)+ self.repo = Path(temp_dir.name)+ for target in (+ patch.dict(os.environ, strip_local_git_env(os.environ.copy()), clear=True),+ patch("canonical_completion_guard.REPO_ROOT", self.repo),+ patch("canonical_completion_guard.SUBSYSTEM_REGISTRY", self.repo / self.REGISTRY),+ patch("repo_file_io.REPO_ROOT", self.repo),+ patch("subsystem_contracts.REPO_ROOT", self.repo),+ patch("subsystem_contracts.CONTRACTS_DIR", self.repo / self.SUBSYSTEMS),+ ):+ target.start()+ self.addCleanup(target.stop)+ self.git("init", "-q", "-b", "main")+ self.git("config", "user.name", "Pulse Test")+ self.git("config", "user.email", "[email protected]")+ self.revision = 0+ self.commit(+ "base",+ {+ self.REGISTRY: self.registry(),+ self.CONTRACT: self.contract(),+ self.GO_RUNTIME: "package alpha\n",+ self.GO_PROOF: "package alpha\n",+ self.GO_UNCOVERED: "package sub\n",+ self.TS_RUNTIME: "export const widget = 1;\n",+ self.TS_PROOF: "import { widget } from '../widget';\n",+ self.TS_PINNED: "export const pinned = 1;\n",+ self.TS_PIN_PROOF: (+ "import { readFileSync } from 'node:fs';\n"+ "const source = readFileSync('src/alpha/pinned.ts', 'utf8');\n"+ "expect(source).toContain('pinned');\n"+ ),+ },+ )++ def registry(self) -> str:+ rule = {+ "id": "alpha",+ "contract": self.CONTRACT,+ "owned_prefixes": ["app/alpha/", "frontend-modern/src/alpha/"],+ "owned_files": [],+ "verification": {+ "allow_same_subsystem_tests": False,+ "test_prefixes": [],+ "exact_files": [],+ "require_explicit_path_policy_coverage": True,+ "path_policies": [+ {+ "id": "alpha-runtime",+ "label": "alpha runtime proof",+ "match_prefixes": ["app/alpha/", "frontend-modern/src/alpha/"],+ "match_files": [],+ "allow_same_subsystem_tests": False,+ "test_prefixes": [],+ "exact_files": [self.GO_PROOF, self.TS_PIN_PROOF, self.TS_PROOF],+ }+ ],+ },+ }+ return json.dumps({"subsystems": [rule]}, indent=2) + "\n"++ def contract(self) -> str:+ self.revision = getattr(self, "revision", 0) + 1+ return (+ "# alpha contract\n\n"+ "## Contract Metadata\n\n"+ "```json\n"+ '{"subsystem_id": "alpha"}\n'+ "```\n\n"+ "## Current State\n\n"+ f"Alpha owns the widget (revision {self.revision}).\n"+ )++ def git(self, *args: str) -> str:+ return subprocess.run(+ ["git", *args],+ cwd=self.repo,+ check=True,+ capture_output=True,+ text=True,+ ).stdout.strip()++ def write(self, files: dict[str, str]) -> None:+ for rel, text in files.items():+ path = self.repo / rel+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(text, encoding="utf-8")+ self.git("add", *files)++ def commit(self, message: str, files: dict[str, str]) -> str:+ self.write(files)+ self.git("commit", "-q", "-m", message)+ return self.git("rev-parse", "HEAD")++ def change(self, runtime: str, text: str) -> str:+ return self.commit(f"change {runtime}", {runtime: text, self.CONTRACT: self.contract()})++ def run_guard(self, commit: str) -> tuple[int, str]:+ files = self.git("diff-tree", "--no-commit-id", "--name-only", "-r", commit)+ stderr = io.StringIO()+ with (+ patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}),+ patch("sys.stdin", io.StringIO(files + "\n")),+ redirect_stderr(stderr),+ ):+ status = main(["--files-from-stdin", "--diff-base", f"{commit}^", "--commit", commit])+ return status, stderr.getvalue()++ def test_untouched_covering_go_proof_satisfies_verification(self) -> None:+ commit = self.change(self.GO_RUNTIME, "package alpha\n\nconst Size = 2\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 0, stderr)++ def test_untouched_covering_ts_proof_satisfies_verification(self) -> None:+ commit = self.change(self.TS_RUNTIME, "export const widget = 2;\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 0, stderr)++ def test_runtime_file_no_proof_exercises_still_blocks(self) -> None:+ commit = self.change(self.GO_UNCOVERED, "package sub\n\nconst Size = 2\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 1)+ self.assertIn("- subsystem alpha: missing verification artifact for alpha runtime proof", stderr)+ self.assertIn(f" no acceptable proof below already exercises:\n {self.GO_UNCOVERED}", stderr)++ def test_source_text_pin_is_not_coverage(self) -> None:+ commit = self.change(self.TS_PINNED, "export const pinned = 2;\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 1)+ self.assertIn(f" {self.TS_PINNED}", stderr)++ def test_partially_covered_change_blocks_on_the_uncovered_file(self) -> None:+ self.write({self.GO_UNCOVERED: "package sub\n\nconst Size = 3\n"})+ commit = self.change(self.GO_RUNTIME, "package alpha\n\nconst Size = 3\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 1)+ uncovered = stderr.split("already exercises:\n", 1)[1].split("\n make one", 1)[0]+ self.assertEqual(uncovered, f" {self.GO_UNCOVERED}")++ def test_staged_proof_still_satisfies_an_uncovered_change(self) -> None:+ self.write({self.GO_PROOF: "package alpha\n\nfunc TestSize() {}\n"})+ commit = self.change(self.GO_UNCOVERED, "package sub\n\nconst Size = 4\n")+ status, stderr = self.run_guard(commit)+ self.assertEqual(status, 0, stderr)++ def test_coverage_is_read_from_the_evaluated_commit(self) -> None:+ covered = self.change(self.TS_RUNTIME, "export const widget = 5;\n")+ self.commit("proof stops importing the widget", {self.TS_PROOF: "export {};\n"})+ uncovered = self.change(self.TS_RUNTIME, "export const widget = 6;\n")++ status, stderr = self.run_guard(covered)+ self.assertEqual(status, 0, stderr)+ status, stderr = self.run_guard(uncovered)+ self.assertEqual(status, 1)+ self.assertIn(f" {self.TS_RUNTIME}", stderr)++ def test_reader_skips_directories_without_losing_its_place(self) -> None:+ commit = self.git("rev-parse", "HEAD")+ with GitTextReader(commit, repo_root=self.repo) as read:+ self.assertIsNone(read("frontend-modern/src/alpha"))+ self.assertIsNone(read("frontend-modern/src/alpha/missing.ts"))+ self.assertEqual(read(self.TS_RUNTIME), "export const widget = 1;\n")+ with GitTextReader(None, repo_root=self.repo) as read:+ self.assertIsNone(read("app/alpha"))+ self.assertEqual(read(self.GO_PROOF), "package alpha\n")++ def test_pre_commit_mode_reads_coverage_from_the_index(self) -> None:+ self.write({self.GO_RUNTIME: "package alpha\n\nconst Size = 7\n", self.CONTRACT: self.contract()})+ stderr = io.StringIO()+ with patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}), redirect_stderr(stderr):+ self.assertEqual(main([]), 0, stderr.getvalue())++ self.write({self.GO_UNCOVERED: "package sub\n\nconst Size = 7\n"})+ stderr = io.StringIO()+ with patch.dict(os.environ, {CONTRACT_NEUTRAL_OVERRIDE_ENV: ""}), redirect_stderr(stderr):+ self.assertEqual(main([]), 1)+ self.assertIn(f" {self.GO_UNCOVERED}", stderr.getvalue())++if __name__ == "__main__":unittest.main()diff --git a/scripts/release_control/proof_coverage.py b/scripts/release_control/proof_coverage.pynew file mode 100644index 0000000000..4a6e2d7fab--- /dev/null+++ b/scripts/release_control/proof_coverage.py@@ -0,0 +1,357 @@+#!/usr/bin/env python3+"""Decide whether an existing proof test covers a touched runtime file.++The canonical completion guard used to accept a runtime change only when one+of the registered proof files was staged with a diff. The cheapest diff was+one more `expect(source).toContain(...)` pin, so registered proof files grew+thousands of source-text pins that proved nothing about behaviour. A proof+that already exercises the touched file and runs in CI is real verification+whether or not this commit edits it.++Coverage is a static relation between the proof file and the runtime file,+read from the tree under evaluation (the index before a commit exists, the+commit itself in CI):++- Go: the proof is a `_test.go` file compiled with the runtime file's package+ (same directory) or importing that package in its import declarations, and+ no build tag beyond a platform keeps it out of the default test run.+- TypeScript/JavaScript: the proof imports the runtime module (relative or+ `@/` specifier). Reading the module's source as text does not count, neither+ through `readFileSync` nor through a Vite `?raw` import; a type-only import+ does not run the module, and a mocked module runs the mock.+- Python: the proof imports the runtime module by name at runtime (parsed,+ so docstrings and `if TYPE_CHECKING:` imports do not count).+- Anything else (docs, workflows, shell scripts, JSON): the proof names the+ runtime file's repository path, because reading or executing that file is+ how such files are tested.++CI's required test jobs run every proof file, so "exists and covers" plus a+green CI run is the verification the guard asks for.+"""++from __future__ import annotations++import ast+import posixpath+import re+import subprocess+import sys+from pathlib import Path+from typing import Callable, Dict, Iterable, List, Optional, Sequence++from repo_file_io import git_env+++REPO_ROOT = Path(__file__).resolve().parents[2]+GO_MODULE = "github.com/rcourtman/pulse-go-rewrite"+FRONTEND_SRC = "frontend-modern/src/"++JS_SUFFIXES: tuple[str, ...] = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs")+JS_RESOLVE_SUFFIXES: tuple[str, ...] = (+ "",+ ".ts",+ ".tsx",+ ".js",+ ".jsx",+ ".mjs",+ "/index.ts",+ "/index.tsx",+ "/index.js",+)++# `import x from 'm'`, `import {a,\n b} from "m"`, `export * from 'm'`; the+# `type` group lets type-only imports be skipped because they never run `m`.+JS_STATIC_IMPORT_RE = re.compile(+ r"""(?:^|[;\n])\s*(?:import|export)\s+(type\s+)?[^;'"]*?\bfrom\s*['"]([^'"\n]+)['"]""",+)+JS_SIDE_EFFECT_IMPORT_RE = re.compile(r"""(?:^|[;\n])\s*import\s*['"]([^'"\n]+)['"]""")+# A member call (`obj.require(...)`) or a quoted word is not a module load.+JS_DYNAMIC_IMPORT_RE = re.compile(+ r"""(?<![\w$.'"`])(?:import|require)\s*\(\s*['"]([^'"\n]+)['"]\s*\)"""+)+JS_MOCK_RE = re.compile(+ r"""\b(?:vi|jest)\.(?:mock|doMock)\s*\(\s*(?:import\s*\(\s*)?['"]([^'"\n]+)['"]"""+)+JS_BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)+# `//` after code or at line start; `http://` and `'//cdn'` keep their text.+JS_LINE_COMMENT_RE = re.compile(r"(^|[\s;{},()])//[^\n]*", re.MULTILINE)+JS_TYPE_QUERY_RE = re.compile(r"\btypeof\s+import\s*\(")+GO_BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)+GO_IMPORT_BLOCK_RE = re.compile(r"^import\s*\((.*?)\)", re.MULTILINE | re.DOTALL)+GO_IMPORT_LINE_RE = re.compile(r'^import\s+(?:[\w.]+\s+)?"([^"]+)"', re.MULTILINE)+GO_IMPORT_SPEC_RE = re.compile(r'^\s*(?:[\w.]+\s+)?"([^"]+)"', re.MULTILINE)+GO_BUILD_RE = re.compile(r"^//go:build\s+(.+)$", re.MULTILINE)+# Constraints CI's Go jobs satisfy or that only pick a platform; any other tag+# (`ignore`, `integration`, ...) can keep a test out of the required run.+GO_PLATFORM_TAGS = frozenset(+ {+ "386", "amd64", "arm", "arm64", "cgo", "darwin", "freebsd", "linux",+ "netbsd", "openbsd", "unix", "windows",+ }+)+PATH_CHAR = r"[\w./-]"+++TextReader = Callable[[str], Optional[str]]+++class GitTextReader:+ """Read files from a commit, or from the index when `revision` is None.++ One `git cat-file --batch` process serves every read, so checking a+ requirement's proofs costs one round trip per file rather than a process.+ """++ def __init__(self, revision: str | None, *, repo_root: Path = REPO_ROOT) -> None:+ self.prefix = f"{revision}:" if revision is not None else ":0:"+ self.repo_root = repo_root+ self.process: subprocess.Popen | None = None+ self.cache: Dict[str, Optional[str]] = {}++ def __call__(self, path: str) -> Optional[str]:+ if path in self.cache:+ return self.cache[path]+ if self.process is None:+ self.process = subprocess.Popen(+ ["git", "cat-file", "--batch"],+ cwd=self.repo_root,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ env=git_env(self.repo_root),+ )+ assert self.process.stdin is not None and self.process.stdout is not None+ self.process.stdin.write(f"{self.prefix}{path}\n".encode())+ self.process.stdin.flush()+ header = self.process.stdout.readline().decode("utf-8", errors="replace").split()+ text: Optional[str] = None+ if len(header) == 3:+ # Every found object is followed by its body; a tree (a directory+ # a specifier names) must be drained too or the stream desyncs.+ body = self.process.stdout.read(int(header[2]))+ self.process.stdout.read(1)+ if header[1] == "blob":+ text = body.decode("utf-8", errors="replace")+ self.cache[path] = text+ return text++ def close(self) -> None:+ if self.process is None:+ return+ assert self.process.stdin is not None and self.process.stdout is not None+ self.process.stdin.close()+ self.process.wait()+ self.process.stdout.close()+ self.process = None++ def __enter__(self) -> "GitTextReader":+ return self++ def __exit__(self, *_exc: object) -> None:+ self.close()+++def working_tree_reader(repo_root: Path = REPO_ROOT) -> TextReader:+ """Read files as they are on disk, for lookups made while editing."""++ def read(path: str) -> Optional[str]:+ try:+ return (repo_root / path).read_text(encoding="utf-8", errors="replace")+ except (FileNotFoundError, IsADirectoryError, NotADirectoryError):+ return None++ return read+++def git_tracked_paths(revision: str | None, prefixes: Sequence[str], *, repo_root: Path = REPO_ROOT) -> List[str]:+ """Paths under any of `prefixes` in a commit, or in the index."""+ if not prefixes:+ return []+ if revision is None:+ command = ["git", "ls-files", "-z", "--", *prefixes]+ else:+ command = ["git", "ls-tree", "-r", "-z", "--name-only", revision, "--", *prefixes]+ result = subprocess.run(+ command,+ cwd=repo_root,+ check=True,+ capture_output=True,+ env=git_env(repo_root),+ )+ return sorted(path for path in result.stdout.decode().split("\0") if path)+++def is_js_path(path: str) -> bool:+ return path.endswith(JS_SUFFIXES) and not path.endswith(".d.ts")+++def js_code(text: str) -> str:+ """Drop comments and `typeof import(...)` type queries, which never run a module.++ Stripping is conservative: a `/*` inside a string can only hide imports,+ never invent one.+ """+ text = JS_BLOCK_COMMENT_RE.sub("", text)+ text = JS_LINE_COMMENT_RE.sub(r"\1", text)+ return JS_TYPE_QUERY_RE.sub("typeof ", text)+++def js_import_specifiers(text: str) -> List[str]:+ specifiers = [spec for type_only, spec in JS_STATIC_IMPORT_RE.findall(text) if not type_only]+ specifiers.extend(JS_SIDE_EFFECT_IMPORT_RE.findall(text))+ specifiers.extend(JS_DYNAMIC_IMPORT_RE.findall(text))+ return specifiers+++def js_specifier_targets(importer: str, specifier: str) -> List[str]:+ """Candidate repository paths a module specifier can resolve to, in order.++ A query suffix (`?raw`, `?url`, `?inline`) loads the file as text or an+ asset without running it, which is a source pin, not coverage.+ """+ if "?" in specifier:+ return []+ if specifier.startswith("@/"):+ base = FRONTEND_SRC + specifier[2:]+ elif specifier.startswith("."):+ base = posixpath.normpath(posixpath.join(posixpath.dirname(importer), specifier))+ else:+ return []+ return [base + suffix for suffix in JS_RESOLVE_SUFFIXES]+++def resolve_js_specifier(importer: str, specifier: str, read: TextReader) -> Optional[str]:+ """The one file a specifier loads: the first candidate that exists."""+ return next(+ (path for path in js_specifier_targets(importer, specifier) if read(path) is not None),+ None,+ )+++def go_package_dir(path: str) -> str:+ return posixpath.dirname(path)+++def go_imported_packages(text: str) -> set[str]:+ """Import paths from the file's import declarations, not any quoted string."""+ code = GO_BLOCK_COMMENT_RE.sub("", text)+ packages = set(GO_IMPORT_LINE_RE.findall(code))+ for block in GO_IMPORT_BLOCK_RE.findall(code):+ packages.update(GO_IMPORT_SPEC_RE.findall(block))+ return packages+++def go_test_runs_by_default(text: str) -> bool:+ """False when a build constraint needs a tag CI's Go test jobs do not set."""+ header = text.split("\npackage ", 1)[0]+ for expression in GO_BUILD_RE.findall(header):+ for tag in re.findall(r"[\w.]+", expression):+ if tag not in GO_PLATFORM_TAGS and not re.fullmatch(r"go1\.\d+", tag):+ return False+ return True+++def python_module_names(path: str) -> List[str]:+ """Names a Python test could import the runtime module by.++ A bare name that is also a standard-library module (`json`, `types`)+ would name the stdlib module, not this file.+ """+ stem = posixpath.splitext(path)[0]+ parts = stem.split("/")+ if parts[-1] == "__init__":+ parts = parts[:-1]+ stdlib = set(getattr(sys, "stdlib_module_names", ()))+ names = [".".join(parts[index:]) for index in range(len(parts))]+ return [name for name in names if "." in name or name not in stdlib]+++def _is_type_checking(test: ast.expr) -> bool:+ return (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") or (+ isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"+ )+++def python_imported_modules(text: str) -> set[str]:+ """Modules a Python file imports at runtime, including `from pkg import module`.++ Docstrings, comments and `if TYPE_CHECKING:` imports do not count.+ """+ try:+ tree = ast.parse(text)+ except SyntaxError:+ return set()+ type_only: set[int] = set()+ for node in ast.walk(tree):+ if isinstance(node, ast.If) and _is_type_checking(node.test):+ for child in node.body:+ type_only.update(id(inner) for inner in ast.walk(child))+ modules: set[str] = set()+ for node in ast.walk(tree):+ if id(node) in type_only:+ continue+ if isinstance(node, ast.Import):+ modules.update(alias.name for alias in node.names)+ elif isinstance(node, ast.ImportFrom) and node.module and not node.level:+ modules.add(node.module)+ modules.update(f"{node.module}.{alias.name}" for alias in node.names)+ elif (+ isinstance(node, ast.Call)+ and isinstance(node.func, (ast.Attribute, ast.Name))+ and getattr(node.func, "attr", getattr(node.func, "id", "")) == "import_module"+ and node.args+ and isinstance(node.args[0], ast.Constant)+ and isinstance(node.args[0].value, str)+ ):+ modules.add(node.args[0].value)+ return modules+++def names_repo_path(text: str, path: str) -> bool:+ """The text names `path` itself, not a longer path that ends with it."""+ return re.search(rf"(?<!{PATH_CHAR}){re.escape(path)}(?!{PATH_CHAR})", text) is not None+++def proof_covers_runtime_file(proof: str, runtime: str, read: TextReader) -> bool:+ """Return True when the proof file, as it exists, exercises `runtime`."""+ if proof == runtime:+ return False+ text = read(proof)+ if text is None or read(runtime) is None:+ return False++ if runtime.endswith(".go"):+ if not proof.endswith("_test.go") or not go_test_runs_by_default(text):+ return False+ if go_package_dir(proof) == go_package_dir(runtime):+ return True+ return f"{GO_MODULE}/{go_package_dir(runtime)}" in go_imported_packages(text)++ if is_js_path(runtime):+ if not is_js_path(proof):+ return False+ code = js_code(text)+ # A mocked module is replaced, so importing it runs the mock instead.+ if any(resolve_js_specifier(proof, spec, read) == runtime for spec in JS_MOCK_RE.findall(code)):+ return False+ return any(+ resolve_js_specifier(proof, specifier, read) == runtime+ for specifier in js_import_specifiers(JS_MOCK_RE.sub("", code))+ )++ if runtime.endswith(".py"):+ if not proof.endswith(".py"):+ return False+ imported = python_imported_modules(text)+ return any(name in imported for name in python_module_names(runtime))++ return names_repo_path(text, runtime)+++def covering_proof_files(+ runtime: str,+ candidate_proofs: Iterable[str],+ read: TextReader,+) -> List[str]:+ return sorted(+ {proof for proof in candidate_proofs if proof_covers_runtime_file(proof, runtime, read)}+ )diff --git a/scripts/release_control/staged_commit_shape_guard.py b/scripts/release_control/staged_commit_shape_guard.pyindex 5035e19e41..549b713659 100644--- a/scripts/release_control/staged_commit_shape_guard.py+++ b/scripts/release_control/staged_commit_shape_guard.py@@ -15,9 +15,9 @@ from canonical_completion_guard import (git_staged_files as canonical_git_staged_files,infer_impacted_subsystems,load_subsystem_rules,+ missing_verification_requirements,required_contract_updates,staged_contract_has_substantive_change,- staged_verification_files_for_requirement,)from repo_file_io import load_repo_jsonfrom release_promotion_policy_support import (@@ -252,18 +252,7 @@ def canonical_commit_shape_errors(staged_files: Sequence[str]) -> list[str]:if contract_path in staged_setif not staged_contract_has_substantive_change(contract_path)}- missing_verification: dict[str, dict] = {}- for subsystem_id, data in impacted.items():- missing_requirements = [- requirement- for requirement in data.get("verification_requirements", [])- if not staged_verification_files_for_requirement(data, requirement, staged_files)- ]- if missing_requirements:- missing_verification[subsystem_id] = {- **data,- "missing_requirements": missing_requirements,- }+ missing_verification = missing_verification_requirements(impacted, staged_files)if not missing_contracts and not insufficient_contract_updates and not missing_verification:return []diff --git a/scripts/release_control/subsystem_lookup.py b/scripts/release_control/subsystem_lookup.pyindex 272de17a81..28ae4358ae 100644--- a/scripts/release_control/subsystem_lookup.py+++ b/scripts/release_control/subsystem_lookup.py@@ -10,9 +10,11 @@ from pathlib import Pathimport sysfrom typing import Any+import proof_coveragefrom canonical_completion_guard import (REPO_ROOT,build_verification_requirements,+ candidate_proof_files,infer_impacted_subsystems,is_ignored_runtime_file,is_test_or_fixture,@@ -284,6 +286,7 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:contract_updates = required_contract_updates(normalized, impacted, contract_index=contract_index)path_entries: list[dict[str, Any]] = []unowned: list[str] = []+ read_working_tree = proof_coverage.working_tree_reader(REPO_ROOT)for path in normalized:classification = "runtime"@@ -304,13 +307,25 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:if not subsystem_matches_path(rule, path):continuerequirement = verification_requirement_for_path(rule, path)+ # The guard accepts an existing proof that already exercises+ # the file; report it so nobody edits a proof just to pass.+ covering = (+ []+ if requirement.get("path_policy_gap")+ else proof_coverage.covering_proof_files(+ path,+ candidate_proof_files(requirement, revision=None),+ read_working_tree,+ )+ )matches.append({"subsystem": rule["id"],"contract": rule["contract"],"lane_context": lane_context_for_rule(rule, status_report),"contract_update_required": True,- "proof_update_required": True,+ "proof_update_required": not covering,+ "covering_proof_files": covering,"ownership_basis": ownership_basis_for_path(rule, path),"matched_contract_references": reference_matches_by_subsystem.get(str(rule["id"]),@@ -349,7 +364,8 @@ def lookup_paths(paths: list[str], *, lean: bool = False) -> dict[str, Any]:if path in contract["touched_runtime_files"]],"contract_update_required": classification == "runtime" and bool(matches),- "proof_update_required": classification == "runtime" and bool(matches),+ "proof_update_required": classification == "runtime"+ and any(match["proof_update_required"] for match in matches),})@@ -437,6 +453,12 @@ def render_pretty(result: dict[str, Any]) -> str:f" - {match['subsystem']} -> {match['contract']} "f"[{requirement['id']}: {requirement['label']}]")+ if match.get("covering_proof_files"):+ covering = match["covering_proof_files"]+ more = f" (+{len(covering) - 3} more)" if len(covering) > 3 else ""+ lines.append(" already proved by: " + ", ".join(covering[:3]) + more)+ elif match.get("proof_update_required"):+ lines.append(" proof: no acceptable proof exercises this file yet; stage one")if lane_context and lane_context.get("lane"):lane = lane_context["lane"]gap = lane.get("gap")