Orion Delivery — D2.2 `feat/wallet-truth-reconciliation`¶

To: Vesper From: Orion CC: Atlas, Katja (Captain) Date: 2026-04-19 Re: D2.2 — refuse-to-start gate added per D2.1 HOLD ruling Branch: feat/wallet-truth-reconciliation New commit: dbc9363 (1 new on top of the 8 D2.1 commits) Tests: 26 passing (up from 22)

What changed vs. D2.1¶

One new commit on the branch. No edits to existing D2 / D2.1 commits — the bundle grows rather than rewrites, so the patches you already reviewed are byte-identical.

dbc9363 feat(startup): refuse-to-start gate on halt-threshold truth divergence + --accept-truth-divergence override (FLAG-036 D2.2)   ← NEW
adeddd0 fixup(flag-036): D2.1 pre-trade gate gap-fix + Q3 rate-limit + Q4 doc pin
826209a test(flag-036): D2 test suite — InventoryTruthChecker + realignment event + CLI tool (16 tests)
6f495e5 feat(tools): realign_inventory_to_onchain CLI + realignment event type (FLAG-036)
d5a5650 feat(execution): pre-trade inventory truth gate in submit_intent (FLAG-036)
db21372 feat(engine): wire inventory truth check into startup/runtime/shutdown (FLAG-036)
316a96b feat(halt): DEGRADED state machine + inventory_truth mode transitions (FLAG-036)
47e0cda feat(truth): InventoryTruthChecker core module + strict on-chain wrappers (FLAG-036)
910f765 feat(db): add inventory_truth_snapshots table + wallet_reconciliation config (FLAG-036)

Bundle path: 02 Projects/NEO Trading Engine/patches/feat-wallet-truth-reconciliation-d2.2/ (9 patches).

Gate semantics (per D2.1 ruling)¶

The refuse-to-start gate runs once, at startup, right after the initial inventory truth check returns:

startup truth status	`--accept-truth-divergence`	Behavior
`ok`	either	Silent pass. No state writes. No extra log.
`warn`	either	`log.warning("[STARTUP_WARN] ... — starting normally")`. Engine proceeds.
`halt` / `escalate_to_halt`	not set	`RuntimeError` with structured operator message (delta values, realign command, override hint). `halt.reason = "startup_failure"` and `halt.detail = "startup_gate_refused: ..."` persisted. Session runner raises out of `_startup()`, exit code non-zero.
`halt` / `escalate_to_halt`	set	`log.warning("[STARTUP_GATE_OVERRIDE] ...")`. Three audit keys persisted on `engine_state`: `startup.truth_divergence_acknowledged = "1"`, `startup.truth_divergence_delta_xrp`, `startup.truth_divergence_delta_rlusd`. Engine then runs `_apply_truth_check_result`, which puts it in `DEGRADED`; C5 pre-trade gate blocks quoting until a subsequent check recovers to `ok`.

The gate runs before _apply_truth_check_result so a refused session leaves no DEGRADED ghost row on engine_state. The DEGRADED row only appears when the operator has explicitly overridden.

Code shape¶

Logic extracted into NEOEngine._apply_startup_truth_gate(result, *, accept_truth_divergence) so the four arms are unit-testable without a full engine fixture. _startup now:

def _startup(
    self,
    *,
    parent_session_id: Optional[int] = None,
    accept_truth_divergence: bool = False,
) -> None:
    ...
    if self._config.wallet_reconciliation.enabled:
        log.info("Running startup inventory truth check")
        _startup_result = None
        try:
            _startup_result = self._inventory_truth.check("startup")
            self._last_truth_check_ts = time.time()
        except Exception as exc:
            log.error("Startup inventory truth check raised — continuing startup", ...)

        if _startup_result is not None:
            # Refuse-to-start gate runs BEFORE _apply_truth_check_result
            # so a refused session leaves no DEGRADED ghost row behind.
            self._apply_startup_truth_gate(
                _startup_result,
                accept_truth_divergence=accept_truth_divergence,
            )
            self._apply_truth_check_result(_startup_result)
            log.info("Startup inventory truth check complete", ...)

Refusal message (verbatim from the RuntimeError):

STARTUP REFUSED — inventory truth divergence exceeds halt threshold.
  delta_xrp:   -43.8700 XRP
  delta_rlusd: +0.0000 RLUSD
  status:      halt

The engine cannot prove alignment with on-chain truth. Options:
  1. Realign internal inventory to on-chain balances:
       python tools/realign_inventory_to_onchain.py --confirm
  2. Or start anyway in DEGRADED mode (quoting blocked until
     a subsequent truth check returns ok):
       rerun with --accept-truth-divergence

CLI wiring: run_paper_session.py now accepts --accept-truth-divergence (argparse action="store_true"). Threaded through run_paper_session(...) as a kwarg into engine._startup(accept_truth_divergence=...). Default is False, so existing invocations are unaffected.

Tests¶

4 new tests in Part E, all passing:

test_23_startup_refuses_on_halt_without_override              PASSED
test_24_startup_permits_on_halt_with_override_and_persists_audit  PASSED
test_25_startup_warn_logs_warning_but_does_not_raise          PASSED
test_26_startup_ok_is_silent                                  PASSED

Full suite: python -m pytest tests/test_flag_036_wallet_truth_reconciliation.py -v → 26 passed in 0.48s.

Coverage:

test_23 asserts RuntimeError with "STARTUP REFUSED", the signed delta, the realign command, and the override flag name; asserts halt.reason = "startup_failure" and halt.detail contains startup_gate_refused; asserts the override audit key is not set.
test_24 asserts the [STARTUP_GATE_OVERRIDE] WARNING is emitted; asserts the three startup.truth_divergence_* audit keys are persisted with the right values; asserts halt.reason is not written (so dashboards don't misattribute the override session as a failed startup).
test_25 asserts WARN does not raise regardless of the override flag; asserts the [STARTUP_WARN] log is emitted; asserts no halt keys or override audit keys are written.
test_26 uses a dedicated log handler to assert zero gate log lines and zero state-manager writes on ok — confirms the silent-pass contract.

Fixup diffstat¶

 neo_engine/main_loop.py                            | 188 ++++++++++++++++++--
 run_paper_session.py                               |  19 ++-
 tests/test_flag_036_wallet_truth_reconciliation.py | 207 +++++++++++++++++++++
 3 files changed, 395 insertions(+), 19 deletions(-)

Apply instructions (Windows)¶

From C:\Users\Katja\Documents\NEO GitHub\neo-2026\, assuming a clean main:

git checkout -b feat/wallet-truth-reconciliation main
git am "C:\Users\Katja\Documents\Claude Homebase Neo\02 Projects\NEO Trading Engine\patches\feat-wallet-truth-reconciliation-d2.2\*.patch"
python -m pytest tests/test_flag_036_wallet_truth_reconciliation.py -v

Or, if D2.1's 8 patches are already applied and you just want the new commit:

git am "C:\Users\Katja\Documents\Claude Homebase Neo\02 Projects\NEO Trading Engine\patches\feat-wallet-truth-reconciliation-d2.2\0009-feat-startup-refuse-to-start-gate-on-halt-threshold-.patch"

Expected: 26 passed in ~0.5s.

Operator impact¶

Normal sessions: unchanged. ok → silent pass, no new output.
Sub-halt drift at startup: new [STARTUP_WARN] line at session start. Non-blocking.
Halt-threshold divergence at startup: engine refuses to start. The RuntimeError message is the operator's instruction manual — realign the wallet or rerun with --accept-truth-divergence.
Override runs: the session starts in DEGRADED. The session log clearly shows [STARTUP_GATE_OVERRIDE] and the three startup.truth_divergence_* keys are in engine_state for the audit trail.

Core invariant (Atlas-locked Apr 19) is now enforced at startup:

"If the engine cannot prove alignment with reality, it does not act."

Status¶

If this reads clean, ship D2.2 as-is. No new open questions this round.

— Orion 2026-04-19, D2 → D2.1 → D2.2

Orion Delivery — D2.2 feat/wallet-truth-reconciliation¶