# Architecture Invariants

OpenContracts enforces a small number of cross-cutting rules at the
codebase level — they're the "this MUST stay true" claims that hold the
permissioning, service-layer, and security model together. Each
invariant is enforced by **both** a pytest test (CI) **and** a Django
system check (`manage.py` startup), pointing at the same scanner, so a
violation cannot slip through one and reach `main`.

This page is the index. Per-invariant detail (recipes, rationale, full
service catalogue) lives in the doc each invariant links to.

## Currently enforced

### Service-layer access in `config/graphql/` (`opencontracts.E001`)

**Rule.** GraphQL resolvers / mutations / types in `config/graphql/`
must reach models through `opencontractserver/<app>/services/` —
never inline `visible_to_user`, `user_can`, or
`user_has_permission_for_obj`.

**Scope of mechanical enforcement.** Both the system check and the pytest
invariant scan **`config/graphql/` only** (recursively, including
subpackages such as `permissioning/permission_annotator/`). The same rule
is *policy* for the other user-context surfaces — MCP tools
(`opencontractserver/mcp/`), LLM tools (`opencontractserver/llms/tools/`),
REST views, and user-context Celery tasks — but those are **not** scanned
today and still contain correct-but-inline Tier-0 calls. A green
`opencontracts.E001` means "no inline Tier-0 in `config/graphql/`," not
"none anywhere." Expanding the scan (after migrating their existing inline
usage) is tracked as future work.

**Why.** Phase 6 of the Service Layer Centralization initiative (issue
#1720). The forbidden identifiers are Tier-0 authorization primitives;
the public entry point for any user-context caller is the service
layer. Inline use bypasses the request-scoped permission cache, scatters
permission logic across hundreds of resolvers, and silently re-implements
IDOR-prevention semantics that the service layer already encodes.

**Where it fires.**
- **Django system check** —
  `opencontractserver/shared/checks.py::check_graphql_service_layer`,
  registered from `opencontractserver/users/apps.py::UsersConfig.ready`.
  Emits `Error` with id `opencontracts.E001`. Blocks every
  `manage.py` command (`runserver`, `migrate`, `shell`, `test`,
  `check --deploy`) with a non-zero exit code.
- **Pytest invariant** —
  `opencontractserver/tests/architecture/test_graphql_service_layer.py`.
  Fires in CI on every push.

**Source of truth.**
`opencontractserver/shared/architecture_audit.py` holds the AST scanner,
the `ALLOWED_FILES` allowlist, and `format_violation` which builds the
failure messages. Both enforcement surfaces call into this module so
the rule has one definition.

**How to fix a violation.** The error message itself prints a
copy-pasteable recipe for each forbidden identifier; you don't need
to leave the failure output for the 95% case. The same recipes (with
extra context and the full per-app service catalogue) live in
[`docs/architecture/query_permission_patterns.md`](../architecture/query_permission_patterns.md),
section "Migration Recipes".

**How to extend the allowlist.** The allowlist
(`opencontractserver.shared.architecture_audit.ALLOWED_FILES`) is a
last-resort escape hatch, not Phase-6-leftover debt. Each entry MUST
have a comment explaining why the file can't migrate. As of this
writing the allowlist is empty: every `config/graphql/` module is
scanned, and `filters.py` no longer needs an entry because its only
remaining references to forbidden identifiers are inside comments
(which the AST scanner already ignores). If you think you need a new
entry, write the justification in the comment and expect reviewer
pushback asking whether a per-app service method would suffice instead.

## Adding a new architecture invariant

The Phase-6 invariant is the pattern. To add another:

1. **Write the scanner** in `opencontractserver/shared/`. Pure
   Python — no Django imports — so it can run from inside
   `AppConfig.ready()`.
2. **Add a `format_violation`-style helper** so the failure message
   carries the copy-paste fix. Devs hitting your check for the first
   time shouldn't need to chase a doc link to know what to type.
3. **Register a Django system check** in
   `opencontractserver/shared/checks.py` (or a sibling module). Use
   `@register("architecture")` and a fresh `opencontracts.EXXX` id.
4. **Wire it into an existing `AppConfig.ready`** (the `users` app is
   the canonical home — see how the Phase-6 check is wired in
   `opencontractserver/users/apps.py`).
5. **Add the pytest invariant** under
   `opencontractserver/tests/architecture/`. Reuse the same scanner;
   add regression tests pinning the Django check's registered state
   and the agreement between both enforcement surfaces.
6. **Document the rule here.** Section name = invariant name. Link the
   detail doc with recipes and rationale.

The whole point of running the check in TWO places (pytest + Django
startup) is so devs get the failure on their **first** `manage.py`
invocation, not when CI runs hours later.
