Orchestrata Ultimate › Gates › env-contract

Gate: env-contract

At a glance

What it refuses

A production entrypoint whose import closure reaches an infra-config read (a RUL-003 endpoint key, or a raising resolver seam) without ever reaching a registered env loader — and, in the other direction, a second mutating dotenv loader appearing under src/.

Why it exists

The module docstring quotes the ruling verbatim:

"RUL-019 — Config modules use Pydantic BaseSettings, and env files must be auto-loaded by every entrypoint via _load_dotenv() (secrets-only .env, then the active ORCHESTRATA_ENV_PROFILE overlay env/{dev,test,prod}.env with override=True) — never left to direnv or manual sourcing."

And records the measured state that made it mechanizable:

"There is NO canonical two-phase loader in src/ … src/ carries three DIVERGENT copies, none of which does the profile overlay … Two production entrypoints reach a REQUIRED raising infra seam and load nothing: agents/runtime_main.py … and knowledge_graph/server.py … Both are launched by systemd ExecStart under deploy/ and survive only on EnvironmentFile= injection. Verified empirically, not theoretically: env -i .venv/bin/python -m orchestrata_ultimate.agents.runtime_main → rc=1, CXPConfigError '…define one in .env.' The process names .env in its own failure message and never reads it."

The ruling's other clause ("config modules use Pydantic BaseSettings") is explicitly NOT mechanized: "It has no falsifiable subject … That clause stays a second none (judgment) bullet on the ruling page."

How it runs

• Command: python scripts/check_env_contract.py [--repo-root PATH] [--max-depth N] [--json]
• When it fires: the scripts/gates.py battery (registered as env-contract); scripts/health_check.py.
• The entrypoint universe ("enumerable, deterministic; never 'the file is called cli.py'"):
  • E1 — [project.scripts] targets in pyproject.toml resolving under src/.
  • E2 — ExecStart= lines under deploy/ invoking python -m <mod> or a src/ path (backslash continuations joined first — "a line-wise regex would silently miss the kernel unit entirely, and a missed entrypoint is a FALSE NEGATIVE, the worse direction here").
  • E3 — src/**/*.py carrying a top-level if __name__ == "__main__":.
• The two rules:
  • Rule B — COVERAGE (the ruling): every in-scope entrypoint's closure must reach a call to a REGISTERED env loader ("an explicit short list, never a name heuristic"). Reachability, not unconditional execution — a hermetic-test guard (if env is None:) legitimately counts.
  • Rule A — LOADER CONFORMANCE / NO DUPLICATES: at most ONE module under src/ may define a MUTATING dotenv loader, and that one must reference ORCHESTRATA_ENV_PROFILE, an env/ profile path, and apply the profile with OVERRIDE. "Rule A is what stops Rule B being satisfiable by a stub." Non-mutating .env READERS are deliberately not flagged.
• Depth bound, measured not assumed: the trigger search is bounded (--max-depth, default 1) because "unbounded, the gate reports 16 violations; 14 of them trace to ONE trigger site … Importing the adapter reads nothing … A gate that fires there gets switched off, and a switched-off gate enforces nothing." The bound "errs toward FALSE NEGATIVES … and it is VISIBLE, never silently dropped — every run reports deep_scope_only" (raise with --max-depth -1 to audit).
• Scope limit, stated: "this gate proves an entrypoint REACHES a conforming loader; it does not prove the loader RAN before the first infra read (ordering). … Do not claim ordering coverage."
• Inputs: fingerprint root ("src",) only (the GATES entry in scripts/gates.py, read through the AST toolkit on 2026-10-23). An earlier version of this page listed pyproject.toml and deploy as roots "ADDED in the 2026-08-28 audit"; the registry on origin/master (a4cbc2bdf) does not carry them. Both feed the entrypoint universe (E1, E2), so an entrypoint added or removed only in pyproject.toml or under deploy/ leaves the cached PASS standing (derived from the code, not measured).
• Caching: the verdict is cached in .cache/gates.json against _fingerprint(("src",)): a sha256 over the relative path and bytes of every file under src/ whose suffix is .py, .toml, .pl, .json, .md or .sh (_interesting()). There is no per-gate suffix mask: this page previously quoted one, and git log --all -S GATE_MASKS -- scripts/gates.py finds no commit that ever contained a GATE_MASKS table.

Typical failures and how to fix them

• Exit codes: "Exit 0 clean, 1 on any violation, 2 when the tree cannot be analysed at all (no src/, unparseable infra_env_rule.py)."
• What a failure looks like (representative): an in-scope entrypoint named with the trigger it reaches and the missing loader (Rule B), or a second mutating loader module named (Rule A).
• Un-blocking: wire the entrypoint to the canonical loader (import it and call it at startup); never add a parallel loader — Rule A exists to refuse exactly that.
• A deploy/ or pyproject.toml entrypoint change that the battery skips. The battery reuses its cached PASS because neither path is a fingerprint root. Force a fresh verdict with python scripts/gates.py --only env-contract --all.

Wiring

• Invokers: scripts/gates.py (battery), scripts/health_check.py.
• Declared as: the gate scripts/check_env_contract.py RUL-019 mechanism on the ruling page rulings/RUL-019-pydantic-dotenv-config-pattern.md — which rulings_lint verifies by literal substring.
• Tests: tests/scripts/test_check_env_contract.py.

Related

• Gates master index
• Development workflow
• RUL-019 — Config modules: Pydantic BaseSettings + auto-loaded .env
• RUL-003 — Env config from the active env profile
• rulings-lint — verifies the RUL-019 gate declaration by literal substring
• env-subnet-scheme — what the profile files must contain; this gate forces processes to read them
• validate-ci — Gates 12–14 are the CI-side env-ownership cousins