[anth-volk]

Fixes #4190

Corrected after merge. This PR merged at e19f0d5. The fixes from its last self-review round (0dc5686 and 12889c2) were pushed after the merge, so they aren't in it; they are in #4205. This description now says what merged, and notes where #4205 changes it.

Summary

Adds the v2-layers quality guard. It gives every API v2 route and service file a layer from its file name alone, and checks each layer's imports and calls. It turns three doc-only v2 rules into checked ones and adds three rules. This is step 2.6 of the agent-proof code-quality plan (its AST part), and builds on #4184 (Import Linter, merged).

Eight files whose names gave no layer are renamed to fit. Open pull requests that import them need updating; see below.

What the guard checks

scripts/rules/v2_layers.py (786 lines) assigns the layers, reads exceptions, scans the files, runs the per-file import and call checks and compares findings with the baselines. #4205 moves the per-file checks to a new scripts/rules/v2_layer_checks.py, so that both stay under the 800-line limit. The guard uses the standard library only, like the rest of the rules tool, and scripts/run_quality_guards.py runs the guard in the quality-guards job of pr.yml.

Rule	Checks	Status
api.v2.files-assigned-to-layers (new)	Every .py file under policyengine_api/services/v2 and policyengine_api/fastapi_routes/v2 gets a layer from its file name. A file whose name gives none fails.	enforced
api.v2.routes-no-sessions-or-sql (was doc-only)	Applies to every module under fastapi_routes/v2. No forbidden imports: SQLAlchemy, SQLModel, a connector, a database_session module, the v1 ORM module policyengine_api.data.orm or policyengine_api.data.v2.database. No SQLAlchemy or SQLModel calls, except its exception classes. No method calls on a session, including a database_session container's read() or transaction(). No session factories, including an injected *session_factory.	ratcheted, 4 tolerated
api.v2.services-no-sql (was doc-only)	Applies to services.py modules. From SQLAlchemy and SQLModel, they import only the Session type and sqlalchemy.exc. They call no SQLAlchemy or SQLModel function except its exception classes and session factories. This catches and_, or_, func and col, even through import sqlalchemy.exc. No data-access session methods: exec, execute, add, get, get_one, the bulk methods, connection, delete and so on. No FastAPI or Starlette imports. Services may open sessions, which the rule's statement doesn't forbid.	enforced, 0 today
api.v2.connectors-never-commit (was doc-only)	Applies to connector modules and a database_connectors/__init__.py. No commit, rollback, close, begin, begin_nested, reset or invalidate on a session. They open no session: no session factory, no injected session_factory, no container read() or transaction(). No imports of the v1 ORM, the v2 database or a database_session module.	enforced, 0 today
api.v2.session-modules-no-data-access (new)	database_session.py modules sit directly in their resource package. No data-access session methods (add, get, merge, exec, execute and so on). No SQL builders. No connector imports. They open, commit, roll back and close sessions.	enforced, 0 today
api.v2.pure-modules-no-session-calls (new)	Applies to validators, transformations, types, process-state modules, package __init__ files, and files under services/v2 that a [[rule.exception]] names. From SQLAlchemy and SQLModel, they import only the Session type. No connector, session, v1 ORM or v2 database imports. No method calls on a session, no SQLAlchemy or SQLModel calls and no session factories.	enforced, 0 today

The fourth doc-only rule, api.v2.connectors-no-cross-calls, became ratcheted in #4184 through Import Linter's independence contract.

Layers by file name (no manifest):

• Under services/v2/<resource>/:
  • services.py, validators.py, transformations.py and types.py;
  • process_state.py, for data a service keeps for the process;
  • database_session.py, which must sit directly in its resource package, where api.v2.session-modules-no-queries (pytest) also checks it;
  • database_connectors/<creates|reads|updates|deletes>[_name].py.
• Under fastapi_routes/v2/:
  • routes.py and <name>_routes.py;
  • <name>_models.py, for request, response and document schemas;
  • <name>_support.py, for HTTP code the route modules share.
• __init__.py anywhere.

The fix message for an unassigned file lists only the names that give a layer in its directory. It doesn't say where each must sit (for example, database_session.py only directly in a resource package); #4205 adds that.

A file that can't be renamed needs a [[rule.exception]] for api.v2.files-assigned-to-layers in rules/registry.toml, with a path, a reason and an expires date. The fix message and v2-code-organization.md ask for these. None is needed today.

• What merged doesn't limit exceptions further; Make v2 file-layer exceptions expire and cover whole files #4205 fixes these gaps:
  • The registry loader requires expires only when an exception sets neither category nor removal, and the guard doesn't check for it. So an exception that sets either and no expires is applied and never ends.
  • The guard doesn't read match, so an exception with match still covers the whole file.
  • The guard applies an exception for a module in a database_connectors package, though api.v2.crud-checks-cover-every-resource still fails a connector module that isn't named after its operation.
• An exception with an expires date fails the rules guard once that date passes, through the registry's existing expiry check.
• An exception chooses no layer. The file gets the route checks under fastapi_routes/v2, or the validator, transformation and types checks under services/v2. The latter don't forbid FastAPI imports, unlike the service checks.
• The guard fails on an exception for:
  • a missing file;
  • a file whose name already gives it a layer;
  • a glob;
  • a path outside the two directories.

Renamed (8 files), with every import updated:

Before	After
services/v2/metadata/selected_catalogs.py	process_state.py
fastapi_routes/v2/errors.py	errors_support.py
fastapi_routes/v2/user_auth.py	user_auth_support.py
fastapi_routes/v2/user_resources.py	user_resources_support.py
fastapi_routes/v2/metadata/common.py	route_support.py
fastapi_routes/v2/metadata/query_dependencies.py	query_support.py
fastapi_routes/v2/metadata/response_cache.py	response_cache_support.py
fastapi_routes/v2/metadata/search_file_response.py	search_file_support.py

metadata/common.py became route_support.py rather than common_support.py: it runs the metadata reads for the route modules, maps their failures to HTTP, and sets the caching headers.

Effects of the renames:

• /v2/openapi.json is unchanged.
• The logger in user_resources_support.py is named after its module, so its name changes from policyengine_api.fastapi_routes.v2.user_resources to ...user_resources_support. No tracked log filter uses the old name.
• households/document_models.py already matched *_models.py.

How calls are recognised.

• Session receivers. A method call counts as a session call only when its receiver is named session or <name>_session.
  • These don't count: the .session of a request or websocket (Starlette's session data, for receivers named request, req, websocket, ws or *_request), and HTTP or client sessions such as http_session, requests_session and _client_session.
  • request_session and request_context.session do count.
  • set.add, cache.get, sessions_router.get and session_ids.add don't count.
• Routes and the pure layers may call no method on a session at all.
• SQL builders. In routes, services and the pure layers, any call into SQLAlchemy or SQLModel counts, except its exception classes. So does <Model>.__table__.<builder>().
• Session factories. Any call into policyengine_api.data.orm or policyengine_api.data.v2.database counts, as do SQLAlchemy's Session, sessionmaker and create_engine, and an injected *session_factory (session_factory(), self._session_factory(), session_factory.begin()).
• Imports. Relative imports and from package import submodule are resolved. Imports made only under TYPE_CHECKING count (decided 2026-11-04).

Tolerated (baseline rules/baselines/v2-layers-routes.txt, 4 entries, one per occurrence).

• These import sqlalchemy.exc to catch SQLAlchemyError:
  • countries/routes.py
  • households/routes.py
  • policies/routes.py
  • user_resources_support.py
• I counted these as violations rather than allowing exception imports in routes, which would mean changing the rule's statement. The fix is for the services to raise typed failures.
• A new finding fails, and so does a baseline entry that no longer occurs.

Limits.

• A session object bound to a name without session in it isn't recognised.
• An alias of a model's table (TABLE = Policy.__table__) isn't recognised.
• A call made through a name re-exported by another module isn't resolved.

Import Linter (#4184) covers the import side transitively.

Open pull requests this affects

I scanned each open PR's head. Once this merges, each needs these changes. The registry baselines can't grow, so each PR must clear its own new findings.

• Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108 (economy reports):
  • Its changed files name a renamed module on 13 lines; it adds 6 of them.
    • Five are imports of fastapi_routes.v2.errors (in countries/ and reports/ routes.py and response_models.py) and of fastapi_routes.v2.user_resources (in reports/routes.py). They raise ModuleNotFoundError until they use the new names.
    • The sixth is the path string "policyengine_api/fastapi_routes/v2/user_resources.py" in its new tests/unit/v2/test_simulation_entrypoint_contract.py. That test reads the file, so it would fail with FileNotFoundError.
  • It edits errors.py and user_resources.py. A simulated merge carries both edits onto the new names without conflict.
  • Because of its old merge base, it also has add/add conflicts with master in countries/routes.py and countries/response_models.py, which this PR doesn't cause.
  • fastapi_routes/v2/reports/routes.py imports sqlalchemy.exc, which fails api.v2.routes-no-sessions-or-sql. The service should raise typed failures for the route to map.
  • All 19 of its new v2 files get a layer from their names.
• Serve household reports at /v2/reports #4132 (household reports, stacked on Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108):
  • It inherits Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108's references and finding, and adds no new references to the old names.
  • Its fastapi_routes/v2/reports/household_response_models.py now gets a layer from the *_models.py rule and needs nothing.
• Calculate stored households through /v2/household-calculations on the v2 household functions #4092 (household calculations):
  • Its changed files name a renamed module on 32 lines; it adds 25 of them. That includes package-form imports such as from policyengine_api.fastapi_routes.v2.metadata import common, which raise ImportError after the rename.
  • It edits metadata/common.py, which this PR renames to route_support.py; a merge reports a modify/delete conflict there.
  • Its branch also carries query_dependencies.py, response_cache.py and selected_catalogs.py from its old merge base, with no edits relative to master. A merge silently keeps those copies alongside the renamed files, and the files rule then flags them. Delete them rather than moving anything.
  • services/v2/household_calculations/simulation_client.py matches no layer name. Either move it out of services/v2 (for example to policyengine_api/libs/), or give it a [[rule.exception]] with an expires date; it then gets the validator, transformation and types checks, which it passes.
  • fastapi_routes/v2/household_calculations/routes.py imports sqlalchemy.exc, the same finding as Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108's.
• Check that every noqa and type: ignore comment names a code and gives a reason #4183 (suppression reasons; now based on master after Check declared dependencies with deptry, with today's findings as a baseline #4178 merged) and Check that every test function asserts something #4188 (stacked on Check that every noqa and type: ignore comment names a code and gives a reason #4183):
  • Check that every noqa and type: ignore comment names a code and gives a reason #4183's rules/baselines/suppressions.txt lists policyengine_api/fastapi_routes/v2/user_resources.py :: from fastapi import Request # noqa: TC002.
  • If this PR merges first, Check that every noqa and type: ignore comment names a code and gives a reason #4183's guard reports that entry as no longer occurring and the same suppression in user_resources_support.py as new, so the entry needs the new path.
  • If Check that every noqa and type: ignore comment names a code and gives a reason #4183 merges first, this PR can't swap the entry for the new path, because the baseline check rejects entries the base branch's copy lacks. Instead, give the # noqa: TC002 in user_resources_support.py a reason and delete the entry.
  • Both PRs add a guard to scripts/run_quality_guards.py and change docs/generated/rules.md, which are text conflicts.

No other open PR adds files under these directories or refers to the renamed modules.

Docs and registry

• v2-code-organization.md has a "File layers" section on the naming rules, exceptions and how calls are recognised. Its HTTP adapter layout uses the new names, and it cites each rule id where it states the rule.
• docs/generated/rules.md and AGENTS.md are regenerated.
• Each rule has proof fixture trees under rules/fixtures/<rule id>/. They include a route that imports a connector, a services file with no layer, and excepted files that get the route or pure-module checks. Make v2 file-layer exceptions expire and cover whole files #4205 adds a route-side file with no layer.

CI and environment variables

• No workflow changes. The guard runs in the existing "Run quality guards" step, with plain python and no project dependencies. Its proofs run in the existing "Test the rules registry tool" step.
• The guard reads no environment variable. It runs git ls-files, through the file-length guard's helper, to list tracked files.

Testing

Each change came test first, in a commit that failed before the change that follows it:

Failing commit	Change
0a8fbe1 (the guard didn't exist)	0240ece
0af97a1	92c10f8
c1e8e66	5ff9ea6
51005e0	efb919d
a4b2b79 (name-only layers, exceptions and the renamed modules' imports)	36fda35
1780783 (rule ids in proofs, exception guidance)	8b441b8
e8ce312 (the exception guidance asks for an expires date)	9b621b1

0dc5686 and 12889c2 (exceptions expire and cover whole files; connector names; fix-message placement; splitting the guard) were pushed after the merge and are in #4205.

Expectations changed in implementing commits, each because of an intended change:

• 0240ece: from .. import database_session (not ...) names the resource's session module.
• 92c10f8: services now also report imports sqlalchemy for import sqlalchemy as sa.
• 5ff9ea6: pure modules and the pure proof also report their sqlmodel.select import.
• 36fda35: one import in test_metadata_route_caching.py was reordered, formatting only.
• 8b441b8: the six bad proof fixtures' expected_findings gained their rule ids, the form 1780783's proofs compare. The test helper's generated exceptions gained the expires date that 1780783's clean-load check requires. Those were test-side failures. The guard change in this commit fixed the two fix-message tests.

e19f0d5 merges master (with #4178's declared-dependencies guard) into this branch. Only scripts/run_quality_guards.py (both guards kept) and the generated docs/generated/rules.md conflicted.

scripts/rules/tests/test_v2_layers.py has 37 tests:

• the six proofs: each tree gives exactly its expected <rule id>: <path> <detail> findings;
• name-only assignment, including process_state.py, *_models.py and *_support.py;
• exceptions: no layer but the route or pure-module checks, and validation of each exception's path (one existing file under the two directories, whose name gives no layer);
• directory-specific fix messages;
• every file in the repository has a layer;
• receiver-aware session calls;
• SQLAlchemy calls and imports per layer;
• TYPE_CHECKING, relative and package imports;
• session factories and containers;
• __table__ builders;
• web sessions;
• baseline counting, stale and duplicate entries.

After the changes:

• the 37 tests pass on Python 3.12 and 3.14;
• the 9 unit test files whose imports changed pass (243 tests);
• the 2 edited integration tests skip here, because V2_MIGRATION_DATABASE_URL isn't set; CI's cross-database job runs them;
• python scripts/run_quality_guards.py, python -m scripts.rules guard --base-ref origin/master, lint-imports --config pyproject.toml, ruff format --check ., ruff check . and mypy pass.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.43590% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 88.44%. Comparing base (97b2232) to head (e19f0d5).
⚠️ Report is 27 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/services/v2/metadata/services.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #4191       +/-   ##
===========================================
+ Coverage   53.84%   88.44%   +34.59%     
===========================================
  Files         283      297       +14     
  Lines       16502    17960     +1458     
  Branches     2681     2975      +294     
===========================================
+ Hits         8886    15885     +6999     
+ Misses       6876     1347     -5529     
+ Partials      740      728       -12     

☔ 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.