[anth-volk]

Fixes #4176

Summary

policyengine_api/data/v2/catalog/catalog_selection.py held catalog version validation, its error types and the SelectedCatalog result type together with the one catalog query, select_catalog. Any v2 validator, transformation or type that needed the version validation or the error types therefore loaded SQLAlchemy and SQLModel, mostly through policyengine_api/query_parameters.py.

• catalog_selection_validation.py: validate_policyengine_version, SUPPORTED_V2_COUNTRY_IDS, MAXIMUM_POLICYENGINE_VERSION_LENGTH, the five error types and SelectedCatalog. It imports no SQLAlchemy, SQLModel or database module, and the table models only under TYPE_CHECKING, for SelectedCatalog's field annotations.
• catalog_selection_reads.py: select_catalog, unchanged. Only the policies and metadata read connectors import it.
• catalog_selection.py is removed. All 15 application modules and 11 test modules that imported it now import one of the two.
• policyengine_api/data/v2/catalog/__init__.py is now only a docstring. It used to import extraction, so importing any module in the package, including the new validation module, loaded SQLModel, SQLAlchemy and every table model. No code used the names it re-exported.
• New rule api.catalog.selection-validation-no-database, enforced by three pytest checks in the Test job (the static and fresh-interpreter import checks, and that the reads module holds the query), with proof fixtures. v2-code-organization.md cites it, and docs/generated/rules.md and AGENTS.md are regenerated.

No behaviour changes. One side effect: SelectedCatalog's field annotations name the table models, which are now imported only under TYPE_CHECKING, so typing.get_type_hints(SelectedCatalog) raises NameError. Nothing reads them at runtime; it would matter only if SelectedCatalog became a Pydantic field or a FastAPI parameter.

Measured effect

Importing each of the 39 v2 validators, transformations and types modules in a fresh interpreter:

• on master, 23 load sqlalchemy;
• on this branch, 3 do (comparison_runs.transformations, identity.transformations, identity.validators), each because it imports the table models at runtime itself, which v2-code-organization.md allows.

In the static import graph (Import Linter 2.15), with the table models' own SQLAlchemy imports set aside, 23 of those modules reached sqlalchemy through catalog_selection before this change and none do after it. This is step 2.5 of the agent-proof code-quality plan and prepares the Import Linter contracts in the next PR. Import Linter does not count the implicit import of a parent package's __init__.py, which is why the runtime check above is a separate test.

Open pull requests this conflicts with

#4108 and #4092 change catalog_selection.py. Their change (deriving SUPPORTED_V2_COUNTRY_IDS from SUPPORTED_COUNTRY_IDS) is already on master. Whichever merges second resolves the conflict by importing from catalog_selection_validation (or catalog_selection_reads for select_catalog). The registry, docs/generated/rules.md and AGENTS.md changes may also conflict as text with other open rule PRs; regenerate with python -m scripts.rules render.

Testing

Tests that show a defect came first, each in its own commit that failed against the code before it:

• 6b189c3: tests/unit/v2/test_catalog_selection_modules.py checks that the validation module imports no database code and the table models only under TYPE_CHECKING; that the reads module defines select_catalog and the validation module validate_policyengine_version; and that no module imports the former one. test_metadata_service.py::test_read_modules_import_no_policyengine_or_v1_metadata_source now checks both new modules, and the 11 test modules that imported the former module import catalog_selection_validation.
• 14b3fcc: test_importing_the_validation_module_loads_no_database_code imports the module in a fresh interpreter and lists the database modules then loaded. It failed with 173 modules loaded, starting with policyengine_api.data.v2.models, until 7c3aba2 emptied the package __init__.py. The same commit added the proof test (fresh-interpreter check only), made the static import helper resolve relative imports and from package import submodule, and added a search for the former module's name.
• f4c11b8: test_the_name_search_matches_module_references_only failed because the search matched the bare word catalog_selection; d8c5c31 narrowed it to module references.

Test coverage added after review, with no failing commit because it checks test helpers rather than application code (95bab05): the proof test also runs the static check on the fixtures, test_only_imports_under_type_checking_count_as_annotation_only pins which imports count as TYPE_CHECKING-only, and the name search reads every tracked file except release notes.

After the changes, run by node ID or by file:

• the 9 tests in test_catalog_selection_modules.py, the updated isolation test and tests/unit/test_supported_countries.py::test_every_country_list_follows_a_country_added_to_the_one_list pass;
• 10 of the 11 test modules whose imports changed pass in full (227 tests); in the 11th, test_supported_countries.py, the one test that uses the import was run (above).

ruff format, ruff check, mypy, python scripts/run_quality_guards.py and python -m scripts.rules guard --base-ref origin/master pass.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.29%. Comparing base (ed52f71) to head (bc6829e).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
...ine_api/data/v2/catalog/catalog_selection_reads.py	86.95%	3 Missing ⚠️
...pi/data/v2/catalog/catalog_selection_validation.py	33.33%	1 Missing and 1 partial ⚠️
...gine_api/services/v2/metadata/selected_catalogs.py	0.00%	1 Missing ⚠️
...engine_api/services/v2/metadata/transformations.py	0.00%	1 Missing ⚠️
...olicyengine_api/services/v2/metadata/validators.py	50.00%	1 Missing ⚠️
.../services/v2/policies/database_connectors/reads.py	50.00%	1 Missing ⚠️
...engine_api/services/v2/policies/transformations.py	0.00%	1 Missing ⚠️
...olicyengine_api/services/v2/policies/validators.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #4179       +/-   ##
===========================================
+ Coverage   53.80%   88.29%   +34.48%     
===========================================
  Files         281      293       +12     
  Lines       16310    17510     +1200     
  Branches     2639     2876      +237     
===========================================
+ Hits         8776    15460     +6684     
+ Misses       6803     1337     -5466     
+ Partials      731      713       -18     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.