Skip to main content

​
Invariant Enforcement Layer

​
Summary (3–6 bullets)

  • Defines automated invariant gates that protect core engineering and data safety rules.
  • Lists current invariants with phase and blocking/warn status.
  • Documents local execution commands and CI integration behavior.
  • Establishes allow-tag policy with required justification and escalation path.
  • Captures stop conditions for false positives and scope-tightening approach.

​
When to use this (3–6 bullets)

  • Before merging changes that touch BigQuery queries, wizard flows, or money paths.
  • When an invariant fails in local checks or CI.
  • When deciding whether an exception needs an allow-tag.
  • When tuning invariant scope to reduce false positives safely.

​
What you’ll walk away with (2–5 bullets)

  • A practical runbook for running and interpreting invariant checks.
  • A clear policy for exceptions without weakening controls.
  • The CI merge expectations for invariant compliance.
Automated invariant gates for Clarity Commission OS. See CLARITY_ENTERPRISE_ENGINEERING_CHARTER.md for governance context.

​
Invariants Enforced

InvariantPhaseBlockingDescription
bq_tenant_filter1✅Every BigQuery query must filter by tenant_id
readiness_requires_period1✅Readiness endpoints must require period_label (no default)
frontend_no_tenant_readiness_in_wizard1✅Wizard must not call tenant-wide readiness (/admin/onboarding/businesses/readiness)
python_no_float1⚠️ WarnNo float() or math.* in money paths (Phase 2: blocking)
frontend_no_dev_panels_prod1⚠️ WarnDebug panels must be guarded for production (Phase 2: blocking)

​
Running Locally

# From repo root
python tools/invariants/run_all.py

# Narrow scope (faster)
python tools/invariants/run_all.py --paths api/bigquery:dashboard/src/pages/ingestion

# Phase 2 (stricter - float + dev panels blocking)
python tools/invariants/run_all.py --phase 2
Individual checks: 
python tools/invariants/python_no_float.py
python tools/invariants/bq_tenant_filter.py
python tools/invariants/readiness_requires_period.py
python tools/invariants/frontend_no_tenant_readiness_in_wizard.py
python tools/invariants/frontend_no_dev_panels_prod.py

​
Allow-Tag Policy

When an invariant must be violated for a justified reason:
  1. Add inline comment on the same line or preceding line: # INVARIANT_ALLOW: <tag>
  2. Must include justification in the same or next line
Example: 
# INVARIANT_ALLOW: tenant_filter — system config lookup, tenant-scoped by caller contract
client.query("SELECT 1 FROM config WHERE key = @key")
Supported tags:
  • float_usage — Python no-float check
  • tenant_filter — BigQuery tenant filter check
Escalation: If you cannot add an allow-tag (e.g. structural limitation), document in an ADR and escalate before merging.

​
CI Integration

.github/workflows/invariants.yml runs on:
  • pull_request to main
  • push to main
Blocking: Invariant failures fail the workflow; PR cannot merge until resolved or allow-tagged with justification.

​
Stop Conditions

If invariant checks produce excessive false positives:
  1. Do not weaken rules silently
  2. Tighten scope (e.g. --paths to narrower directories)
  3. Add allow-tags with justification for known exceptions
  4. Update this doc with scope changes
  5. Escalate if scope tightening is insufficient

​
Deterministic Replay (Phase 3)

See api/tests/test_deterministic_replay_stage1.py for the Stage1 idempotency scaffold. Phase 3 will make deterministic replay blocking.