[anth-volk]

Fixes #4190

Summary

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

What the guard checks

scripts/rules/v2_layers.py uses the standard library only, like the rest of the rules tool. scripts/run_quality_guards.py runs it 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 or from rules/v2-layer-manifest.toml. A file with neither fails.	enforced
api.v2.routes-no-sessions-or-sql (was doc-only)	No module under fastapi_routes/v2 imports SQLAlchemy, SQLModel, a connector, a database_session module, the v1 ORM module policyengine_api.data.orm or policyengine_api.data.v2.database. None calls a SQLAlchemy or SQLModel function (except its exception classes), any method on a session (including a database_session container's read() or transaction()) or a session factory.	ratcheted, 4 tolerated
api.v2.services-no-sql (was doc-only)	services.py modules import nothing from SQLAlchemy or SQLModel but the Session type (for annotations) and sqlalchemy.exc (to raise typed failures). They call no SQLAlchemy or SQLModel function but its exception classes and session factories, which catches and_, or_, func and col even through import sqlalchemy.exc. Services may open sessions, which the rule doesn't forbid. They also call no data-access session method (exec, execute, add, get, get_one, the bulk methods, connection, delete and so on), and import no FastAPI or Starlette.	enforced, 0 today
api.v2.connectors-never-commit (was doc-only)	Connector modules, and a database_connectors/__init__.py, don't call commit, rollback, close, begin, begin_nested, reset or invalidate on a session, open none (no session factory, injected session_factory, or database_session container read()/transaction()), and import no v1 ORM, v2 database or database_session module.	enforced, 0 today
api.v2.session-modules-no-data-access (new)	database_session.py modules sit directly in their resource package and call no data-access session method (add, get, merge, exec, execute and so on) or SQL builder, and import no connector. They open, commit, roll back and close sessions.	enforced, 0 today
api.v2.pure-modules-no-session-calls (new)	Validators, transformations, types, process-state modules and package __init__ files: import nothing from SQLAlchemy or SQLModel but the Session type; import no connector, session, v1 ORM or v2 database module; call no method on a session, no SQLAlchemy or SQLModel function and no session factory.	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:

• services/v2/<resource>/: services.py, validators.py, transformations.py, types.py and database_session.py. A database_session.py must sit directly in its resource package, where api.v2.session-modules-no-queries (pytest) also checks it.
• services/v2/<resource>/database_connectors/: <creates|reads|updates|deletes>[_name].py.
• fastapi_routes/v2/: routes.py and <name>_routes.py, plus request_models.py and response_models.py.
• __init__.py anywhere.

Manifest (9 files with other names). It lives under the code-owned rules/ directory, and each entry gives a layer and a reason:

• http-support: fastapi_routes/v2/errors.py, user_auth.py, user_resources.py, and metadata/{common,query_dependencies,response_cache,search_file_response}.py;
• http-model: households/document_models.py;
• process-state: services/v2/metadata/selected_catalogs.py.

The manifest may give a file under services/v2 only service, validator, transformation, types or process-state, and a file under fastapi_routes/v2 only route, http-model or http-support, so an entry can't switch a file's checks off: each of those layers has the full checks of its layer. Every entry needs a reason. The guard also fails on an entry for a missing file, or for a file whose name already gives it a layer.

Attribute-aware calls.

• A method call counts as a session call only when its receiver is named session or <name>_session. The .session of a request or websocket (Starlette's session data: request, req, websocket, ws or *_request, also as self.request) and HTTP or client sessions (http_session, requests_session, _client_session) don't count; request_session and request_context.session do. So session.add, self._session.exec and database_session.transaction() count; set.add, cache.get, sessions_router.get and session_ids.add don't. Routes and the pure layers may call no method on a session at all, so a method left off a list can't slip through there.
• In routes, services and the pure layers, any call to a name from SQLAlchemy or SQLModel counts, except its exception classes, and so does <Model>.__table__.<builder>(). Connectors may build SQL. A session factory counts for any call into policyengine_api.data.orm or policyengine_api.data.v2.database (get_v1_session_factory, build_v2_session_factory, the engines, …), for SQLAlchemy's Session, sessionmaker and create_engine, and for an injected *session_factory (session_factory(), self._session_factory(), session_factory.begin()). A local helper named select doesn't count.
• 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). countries/routes.py, households/routes.py, policies/routes.py and user_resources.py import sqlalchemy.exc to catch SQLAlchemyError. I counted these as violations rather than allowing exception imports in routes; allowing them 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.
• Services aren't checked for ending transactions themselves, because the rule's statement doesn't forbid it.

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

Open pull requests that add v2 files

I scanned each open PR's head with this guard. Once this merges, each PR must give every new file under services/v2 or fastapi_routes/v2 a layer, by its name or a manifest entry. The baseline can't grow, so each PR must also clear its own new findings.

• Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108 (economy reports; 19 new v2 files against master, 14 not counting __init__.py): every file has a layer. 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.
• 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, 32 new v2 files against master, 24 not counting __init__.py):
  • fastapi_routes/v2/reports/household_response_models.py matches no layer name. Rename it (for example into response_models.py) or add it to rules/v2-layer-manifest.toml as http-model.
  • It inherits Serve economy reports at /v2/reports and save v2 report and simulation IDs #4108's reports/routes.py finding.
• Calculate stored households through /v2/household-calculations on the v2 household functions #4092 (household calculations; 9 new v2 files, 7 not counting __init__.py):
  • services/v2/household_calculations/simulation_client.py matches no layer name. Give it a manifest entry with a layer and a reason (its checks then follow that layer), or move the client out of services/v2.
  • 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.

No other open PR adds files under these directories.

Docs and registry

• v2-code-organization.md has a new "File layers" section on the assignment and how calls are recognised. 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>/, including a route that imports a connector and a file with no layer (shaped after Calculate stored households through /v2/household-calculations on the v2 household functions #4092's simulation_client.py).

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

Tests first, in 4ba6e71, which failed because scripts/rules/v2_layers.py didn't exist yet. The review-round tests failed before their fixes: 5328792 before 834b127, d0a49ed before d18175c, and f7a58d2 before 5af955d.

• scripts/rules/tests/test_v2_layers.py (36 tests):
  • the six proofs: each bad tree gives exactly its expected_findings and each good tree none;
  • assignment by name and by manifest;
  • receiver-aware session calls (set.add not counted);
  • builders counted only when imported from SQLAlchemy or SQLModel;
  • imports under TYPE_CHECKING counted;
  • package and relative imports resolved;
  • connectors may add and flush but not end a transaction;
  • baseline: listed, unlisted and stale findings;
  • the unassigned-file message;
  • manifest validation;
  • every file in the repository has a layer;
  • every layer under services/v2 has its calls checked, and a connector package __init__ counts as a connector;
  • the repository's own session factories;
  • services' SQLAlchemy and SQLModel imports;
  • names that only contain the word session;
  • one baseline line per occurrence;
  • manifest layers per directory, and the required reason;
  • routes and pure layers calling any session method;
  • the full service and connector method lists;
  • manifest files getting their layer's checks;
  • nested session modules;
  • SQLAlchemy calls through import sqlalchemy.exc;
  • web and client sessions;
  • __table__ builders;
  • injected session factories and containers;
  • request and websocket session data by owner.
• Expectations changed in implementing commits, each because of an intended change:
  • 4ba6e71 → 6ae4136: from .. import database_session (not ...) names the resource's session module.
  • 834b127: services now also report imports sqlalchemy for import sqlalchemy as sa.
  • d18175c: pure modules and the pure proof also report their sqlmodel.select import. (The services test's and_, or_, func.lower and col call findings were added in the failing commit d0a49ed.)

After the change:

• the 36 tests pass on Python 3.12 and 3.14;
• python scripts/run_quality_guards.py passes, including v2-layers;
• python -m scripts.rules guard --base-ref origin/master passes;
• ruff format --check ., ruff check . and mypy pass.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (v2-architecture-import-linter@367b2a5). Learn more about missing BASE report.

Additional details and impacted files

@@                       Coverage Diff                        @@
##             v2-architecture-import-linter    #4191   +/-   ##
================================================================
  Coverage                                 ?   88.29%           
================================================================
  Files                                    ?      293           
  Lines                                    ?    17510           
  Branches                                 ?     2876           
================================================================
  Hits                                     ?    15460           
  Misses                                   ?     1337           
  Partials                                 ?      713           

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