Orion Acknowledgment — D2 Rulings Accepted + Branch Plan¶
To: Vesper (she/her) CC: Atlas, Katja (Captain) From: Orion (he/him) Date: 2026-04-19 Re: D1 accepted. Rulings 1–4 + both addenda locked in. D2 commit plan published below. Starting work now.
Rulings — Acknowledged in Full¶
| Ruling | Locked as |
|---|---|
| R1 — thresholds | WARN 1.0 XRP / 2.0 RLUSD, HALT 5.0 XRP / 10.0 RLUSD. Config-tunable via warn_delta_xrp, halt_delta_xrp, warn_delta_rlusd, halt_delta_rlusd. |
| R2 — API failure policy | unverified_halt_count = 3. consecutive_unverified_count resets to zero on status ∈ {ok, warn}. Single / double failure logs but does not halt. |
| R3 — backfill | tools/realign_inventory_to_onchain.py ships in D2. Writes capital_events row with event_type='realignment'. Refuses while engine has active session. Dry-run by default; --confirm required to mutate. |
| R4 — WAC | Out of scope. Filed as FLAG-040, blocked on FLAG-037. |
Addenda — Acknowledged in Full¶
Addendum 1 — Pre-trade gate. Read inventory_truth.status from in-memory state at submit_order entry. ok / warn proceed; halt / degraded block; unverified proceeds with WARNING. No fresh API call per tick — 60s periodic check is the freshness window.
Addendum 2 — DEGRADED mode. State machine becomes ok ↔ warn ↔ DEGRADED → HALT. On entry: cancel all open orders, stop quoting, keep main loop + periodic checks alive. Recovery: status=ok AND consecutive_unverified_count=0. Timeout to HALT after degraded_timeout_s (default 300). engine_state gets inventory_truth.mode, inventory_truth.degraded_since, inventory_truth.degraded_reason. Dashboard label must be prominent.
Branch Plan — feat/wallet-truth-reconciliation¶
Seven commits. Migration first, core second, state machine third, integration last.
| # | Commit | Scope |
|---|---|---|
| C1 | feat(db): add inventory_truth_snapshots + wallet_reconciliation config |
Schema migration (additive). WalletReconciliationConfig dataclass. YAML surface: wallet_reconciliation.*. Defaults per R1/R2 + check_interval_s=60, degraded_timeout_s=300. |
| C2 | feat(truth): inventory truth checker core module |
neo_engine/inventory_truth_checker.py. check() entry point — fetch on-chain, compute delta, classify status, persist snapshot row, emit engine_state keys. Consecutive-unverified counter with reset-on-success. Pure logic, no main-loop integration. |
| C3 | feat(halt): DEGRADED state + inventory_truth status machine |
Extend halt lifecycle with DEGRADED peer state. Entry action: cancel-all + stop-quoting flags. Recovery path. Timeout escalation. inventory_truth.mode engine_state key. |
| C4 | feat(loop): startup + runtime + shutdown truth checks |
Startup: unconditional check at main_loop.py:313–343. Runtime: 60s periodic tick. Shutdown: adjacent to _check_inventory_invariant. All three call InventoryTruthChecker.check(). |
| C5 | feat(exec): pre-trade inventory truth gate |
submit_order reads inventory_truth.status before placement. Block on halt/degraded, log-and-proceed on unverified, proceed on ok/warn. Gate triggers DEGRADED on halt status if periodic check hasn't flipped yet. |
| C6 | feat(tools): realign_inventory_to_onchain one-shot tool |
tools/realign_inventory_to_onchain.py. Active-session lock, dry-run default, --confirm required, realignment row + audit log. Extends record_capital_event for event_type='realignment'. |
| C7 | test: wallet-truth-reconciliation coverage (16 tests) |
10 spec tests + 6 addendum tests. Mocked XRPL API. Deterministic clock for timeout tests. |
Test Inventory (16 total)¶
From original tasking (10): startup ok / warn / halt; runtime interval; shutdown snapshot; phantom-fill baseline; zero-qty pin; mid-session capital event; XRP wrapper; config validation.
From Vesper addendum (6): pre-trade gate ok/halt/unverified; DEGRADED recovery; DEGRADED timeout escalation; engine_state keys on entry/exit.
Three Items Flagged Before Code¶
(a) DEGRADED lives in inventory_truth.mode (new engine_state key), not in halt_reason. HALT via this path uses halt_reason = inventory_truth_halt.
(b) Pre-trade gate placed at submit_order (narrowest funnel), not place_order.
(c) Realignment event_type='realignment' gets explicit skip in classify_withdrawal_basis + unit test. Must not trigger FLAG-031 basis commits.
Halt before C3 if any need a different call.
Sequencing¶
- Now: D2 C1–C7
- After D2 merge:
feat/reconciler-disappeared-order-audit-log(task #86) - After audit logging has session data:
fix/reconciler-disappeared-order-conservative(FLAG-037) - After FLAG-037: FLAG-040 WAC rebuild
— Orion