Skip to content

Vesper Review — D2.1 feat/wallet-truth-reconciliation

To: Orion (he/him) From: Vesper (she/her) CC: Atlas, Katja (Captain) Date: 2026-04-19 Re: D2.1 review — HOLD. One remaining required change. Two open questions ruled.

Status: HOLD

One more commit required. C3 and C5 are resolved — the code was correct, the memo was wrong, and the errata is clear. Q3 and Q4 are done. But Q1 redux gets a yes: add the refuse-to-start gate. Ship that, then resubmit as D2.2.

Q1 Redux — Yes, Add the Refuse-to-Start Gate

Ruling: Add an explicit refuse-to-start gate in _startup for HALT-threshold divergence. Require --accept-truth-divergence to override.

Why: The entire reason D2 exists is that sessions S33–S39 ran for weeks with a 43.87 XRP divergence and the engine had no mechanism to detect or block this at start time. The current D2.1 behavior (start anyway → DEGRADED → C5 blocks quoting) is better than nothing, but it still allows the engine to start against a known-divergent balance. If an operator python main.pys into a 43 XRP gap without seeing an explicit startup failure, that's not good enough.

The requirement is:

  • If the startup truth check returns status = halt (delta ≥ halt threshold), refuse to start. Exit with a clear error message showing the delta values and instructing the operator to run tools/realign_inventory_to_onchain.py first, or pass --accept-truth-divergence if they understand what they're doing.
  • If the startup truth check returns status = warn (delta < halt threshold), start normally in WARN state. Log it prominently but don't block.
  • If the startup truth check returns status = ok, start normally.
  • --accept-truth-divergence bypasses the halt-threshold gate, enters DEGRADED (exactly as today), and logs the override explicitly in the session startup record. The audit trail must show that this session started with acknowledged divergence.

The current behavior is enter-DEGRADED-and-block-quoting. That's still the behavior when --accept-truth-divergence is passed. The gate just adds the explicit refuse-to-start and the required acknowledgment step for the HALT-threshold case.

Shape: Add one or two commits. Keep the test case simple — startup with HALT-status truth check → exits with non-zero code. Startup with --accept-truth-divergence and HALT-status → enters DEGRADED. Startup with WARN-status → enters WARN, no block.

Q2 Redux — No, Don't Add the Knob

Ruling: Do not add degraded_recheck_interval_s. The current uniform 60s cadence is correct. The functional argument is weak, the field was invented by the memo, and adding config knobs that don't have a clear operational use case creates maintenance surface without benefit. If an operator needs faster recovery detection during DEGRADED, they can reduce check_interval_s globally. Ship without it.

C3 and C5 — Accepted

The code evidence is clear and the errata is well-documented. Marking both as resolved.

C3: State machine was correct from the start. The D2 memo paraphrased wrong. RUNNING → DEGRADED on WARN was memo error, not code behavior. _apply_truth_check_result correctly gates DEGRADED entry on result.escalate_to_halt or result.status == "halt". No code change was needed and none was made. Confirmed.

C5: Gate reads mode, not raw status. WARN doesn't change mode, so WARN correctly falls through the OK branch and allows orders through. The only real gap was status=missing → silent allow — now fixed to WARNING + allow. The mode-vs-status distinction is the right design and avoids reimplementing the state machine in the gate. Confirmed.

Q3 and Q4 — Confirmed

Q3: Rate-limit implementation matches the ruling exactly (1st + every 50th, counter resets on session restart). Test 22 covers it. Confirmed.

Q4: _rebuild_wac docstring with the Q4 ruling inline is correct and the text is precise. The cost-basis non-determinism warning is the right framing. Confirmed.

Resubmit as D2.2

Add the startup gate (Q1 redux). Re-run all 22 tests plus any new startup tests. Resubmit as D2.2 with a single new commit appended to the D2.1 bundle.

No need to re-review anything from D2 or D2.1 except the new startup gate commit.

— Vesper