Runtime Certification Gate — canonical pre-push contract

CHANGE-ID: CHG-0051 · TASK-ID: TASK-RUNTIME-GATE · Status: ACTIVE

One command. One answer. python scripts/ci/runtime_gate.py

1. Purpose

The repository has many test families (runtime, features, 50D/70D, models, database, execution, providers, research, CLI, observability, installer, integration). The problem was never test count — it was the absence of ONE strong, trustworthy, repeatable command answering:

"Is the composed runtime safe, coherent, loadable, and operational enough

for an agent to push its change?"

The Runtime Certification Gate is that command. It is a curated, layered certification of the REAL composed runtime — not "run all pytest". It exercises the actual boot path (config → adapter → LiveEngine service graph → decision pipeline → API → shutdown) with disposable persistence and a paper broker.

Doctor (operator diagnostics) and the forensic deploy gate (release health) remain their own contracts; the gate CALLS them, never replaces them.

2. Command

# Recommended (agents, pre-push) — full certification
python scripts/ci/runtime_gate.py

# Machine-readable (pure JSON on stdout)
python scripts/ci/runtime_gate.py --json

# Cheap tier (no runtime boot) — static/import/config/DB-disposable/contract
python scripts/ci/runtime_gate.py --fast

# Persist evidence artifact (artifacts/forensics/runtime_gate_result.json)
python scripts/ci/runtime_gate.py --evidence

Use the repo venv: .venv/Scripts/python.exe scripts/ci/runtime_gate.py (always invoke via the project's venv, never a bare tool name).

Measured budget (2026-09-02, dev workstation):

3. Certification layers

Each stage reports PASS / FAIL / SKIP with duration, evidence, owner, and failure class. A cheap-layer failure SKIPs downstream stages (evidence from a broken foundation is misleading); SKIP is explicit, never silent.

4. Exit codes

Additive to release/exit_codes.py semantics (0..4 aligned; 5 extended):

5. Safety contract

• No live trading. Paper adapter only; a gate tripwire wrapper counts

every execution-seam call (send_order, execute_market_order, place_pending_order, close_position, …) and the whole certification must show 0. This is runtime PROOF, not a claim.

• No production mutation. artifacts/audit.db, artifacts/news.db and

the real app_settings.db are never touched: disposable tmp DBs are injected and NEXUS_SETTINGS_DB is repointed BEFORE runtime import.

• Offline. No provider calls, no MT5 terminal IPC, no downloads. The

only traffic is loopback HTTP to the gate's own in-process FastAPI app.

• Deterministic. Synthetic bars are fixed math series (no random),

timestamps end in the past (no future data), and repeat runs agree.

• Pure stdout contract. --json is pure JSON; engine chatter goes to

stderr (the gate detaches root console handlers before its own output).

6. Failure classification & output

Every failure carries: stage, reason, failure_class, evidence (stdout tail included), and owner (suggested handoff target). Human output ends with RUNTIME CERTIFIED or RUNTIME BLOCKED; every failing stage prints reason/class/owner — never "something failed".

JSON top-level keys: gate_version, timestamp, git_commit, application_version, environment, duration_ms, status, exit_code, stages[], invariants[], model, feature_schema, database, engine, api, shutdown, failures[], warnings[]. Each stage: name, status, duration_ms, evidence, owner, failure_class, reason, skipped_reason.

7. Agent pre-push workflow

agent modifies code
  → python scripts/ci/runtime_gate.py        # canonical gate (this doc)
  → PASS → targeted tests (critical suite per beforePush)
  → commit → push → GitHub CI (final authority)

If the gate fails: do not push. Fix the first failing layer (owner is named in the failure), rerun. The only exception is a failure classified ENVIRONMENT_BLOCKED / MISSING_ARTIFACT that is provably environmental (e.g. artifact not provisioned in CI) — such exceptions are owner-reviewed and recorded in agents/bugs.md or change_control.md, never silent.

8. CI usage

The same canonical command runs as an explicit step in the quality job of .github/workflows/ci.yml (no duplicated logic in YAML — CI invokes the script). CI remains the final authority; the gate is the local fast mirror for the composed-runtime question.

9. Gate testing (the gate tests itself)

• tests/unit/test_runtime_gate.py — 34 tests: exit-code contract, stage

machinery, JSON schema keys, determinism/no-future-data, tripwire behavior, failure-injection classes (missing model, width split, service, shutdown, invariants), upstream-skip semantics, human report, subprocess e2e.

• tests/integration/test_runtime_gate_e2e.py — 9 tests: full-chain

certification, stage order, 70D model/scaler/schema evidence, zero-seam decision-cycle proof, health/shutdown evidence, DB isolation evidence, stdout purity.

10. Failure-injection matrix (mission 28 coverage)

11. Ownership boundary

The gate owns runtime verification/certification orchestration only. It CALLS public certified surfaces (schema_contract, features70, liquidity_runtime, inference_validator, HealthEngine, ForensicHealthEngine, AuditRepository, migration engine) and does NOT redesign installer, provider gate, order manager, policy, regime, replay, shadow, migrations, model training, observability SSOT, or CLI product architecture. Defects found outside the gate are proven and handed off with the failing stage's owner field.