Skip to content

Orion Delivery — Branch #5 audit/config-wiring-pass

To: Katja CC: Vesper, Atlas From: Orion Date: 2026-04-18

Status

Branch #5 complete. Three commits on audit/config-wiring-pass, cut off 83452fe (Branch #4 tip). 39/39 related tests green. Zero regressions vs baseline on the full suite (+5 passed / −5 failed, exactly my five new invariant tests).

Commit SHA Subject
1 143758e feat(strategy): promote clob_switch_threshold_bps to config (Phase 7.3 tuning)
2 2c9280a feat(startup): config invariant check emits config_mismatch on failure
3 8f3fc2f docs(config): add wiring-reference pointer comment to config.py

Patches ready at 02 Projects/NEO Trading Engine/patches/branch-5-config-wiring-pass/ — three numbered .patch files.

What landed, per commit

Commit 1 — promote clob_switch_threshold_bps to config

Removed the hardcoded 3.0 at strategy_engine.py:216. Four surfaces, all default 3.0 per Katja's Q2 ruling — zero behavior change at default.

  • StrategyConfig.clob_switch_threshold_bps: float = 3.0 (new dataclass field, with 6-line comment referencing Atlas Pre-7.3 Review §2C).
  • Loader fallback: strat_raw.get("clob_switch_threshold_bps", 3.0).
  • config/config.yaml: clob_switch_threshold_bps: 3.0 under strategy.
  • config/config.example.yaml: same under strategy.
  • strategy_engine.py CLOB-switch block now reads self._config.strategy.clob_switch_threshold_bps.

Tests: - tests/test_clob_switch_threshold_config.py (new, 6 tests) — default 3.0 preserves behavior (fires at >3, holds at ==3); override 5.0 moves the switch (holds at 4, fires at 5.5); loader default is 3.0; loader reads a YAML override. - tests/test_phase_7_2_clob_switch.py — dropped stale max_inventory_usd=10000.0 kwarg from the fixture. This was a pre-existing FLAG-034 retirement orphan (confirmed pre-existing by stashing my changes). Five Phase 7.2 regression tests now green at the new default.

Commit 2 — config invariant check emits config_mismatch

Added NEOEngine._check_config_invariants(); called from _startup() right after DB init and before engine_status is marked RUNNING. Four invariants per Katja's Q1 ruling:

  1. risk.max_xrp_exposure > 0
  2. risk.max_rlusd_exposure > 0
  3. engine.tick_interval_seconds == strategy.requote_interval_seconds
  4. strategy.clob_switch_threshold_bps > 0

On failure: log.error with the list; persist halt.reason=config_mismatch + halt.detail (joined failure messages); raise RuntimeError. Outer run() wrapper catches, marks engine_status=HALTED, and refuses to start the main loop. HALT_REASON_CONFIG_MISMATCH is no longer a reserved-but-unemitted constant.

Tests: - tests/test_config_invariants.py (new, 5 tests) — 1 happy-path + 4 failure paths, each asserting (a) RuntimeError with "config_mismatch" + offending field name, (b) halt.reason=config_mismatch persisted, (c) halt.detail carries the invariant name. - tests/test_halt_reason_lifecycle.py — extended _make_startup_engine fixture with the four config fields the new check reads (max_xrp=150, max_rlusd=150, tick=requote=4, clob_threshold=3.0). Before, its MagicMock answered any attribute; with a real check in place the fixture needs concrete values. Two tests were flipping fail because of this; with the fixture update they're green again.

Commit 3 — pointer comment to workspace wiring reference

Per Katja's Q3 ruling (option c), the full wiring table stays out of the repo as workspace reference material. Added a six-line docstring pointer at the top of neo_engine/config.py so a code reader who wants the table can find it.

Workspace artifact created: 02 Projects/NEO Trading Engine/[C] NEO Config Wiring Reference.md — every runtime-critical YAML key mapped through dataclass → loader line → runtime consumer → observable metric. ~45 rows. Out-of-scope knobs (parameters.* subtree) noted at the bottom.

Test posture

  • Branch #5-related tests: 39 passed / 0 failed (6 new in test_clob_switch_threshold_config.py, 5 new in test_config_invariants.py, 5 pre-existing fixed in test_phase_7_2_clob_switch.py, 8 in test_halt_reason_lifecycle.py, 19 in test_config.py, remainder spread across).
  • Full suite vs baseline: 466 passed / 373 failed (was 461 / 378). Net +5 passed, −5 failed = exactly my new invariant tests. No regressions.
  • The 373 remaining failures are all pre-existing FLAG-034 max_size_pct_of_portfolio fixture orphans and other baseline suite issues documented on Branch #4. Outside Branch #5 scope.

Copy-paste for Windows VS Code terminal

# Mirror branch from commits
git fetch origin
git checkout -b audit/config-wiring-pass 83452fe

# Apply the three patches
git am "02 Projects\NEO Trading Engine\patches\branch-5-config-wiring-pass\0001-feat-strategy-promote-clob_switch_threshold_bps-to-c.patch"
git am "02 Projects\NEO Trading Engine\patches\branch-5-config-wiring-pass\0002-feat-startup-config-invariant-check-emits-config_mis.patch"
git am "02 Projects\NEO Trading Engine\patches\branch-5-config-wiring-pass\0003-docs-config-add-wiring-reference-pointer-comment-to-.patch"

# Verify
git log --oneline -4
python -m pytest tests/test_clob_switch_threshold_config.py tests/test_config_invariants.py tests/test_phase_7_2_clob_switch.py tests/test_halt_reason_lifecycle.py tests/test_config.py -q

# After Vesper sign-off:
git push -u origin audit/config-wiring-pass

What this unlocks

  • Phase 7.3 offset calibration can now sweep clob_switch_threshold_bps in YAML without code changes.
  • Startup safety — misconfigured runs (e.g., a copy-paste that zeroed a risk cap, or an edit that left tick=4 but requote=8) now fail loud with halt.reason=config_mismatch, not silently. Dashboards already render halt.reason.
  • Audit trail — anyone on the team can walk any YAML key to its observable effect using the wiring reference artifact.

Branch queue after this

Per the locked 7-branch plan:

  • Branch #6 feat/distance-to-touch-diagnostic — primary Phase 7.3 metric (ready to start).
  • Branch #7 fix/wal-checkpoint-hardening — paper shakedown before live (FLAG-035 lands here).
  • S40 after 6+7 merge, then Phase 7.3.

Standing by for Vesper review.

— Orion