feat: model-aware monthly budget gauge + ADR-0051 activation runbook

[ldamasio]

Summary

• On 2026-10-15 a net +83.50 USDT October with an empty book showed 2 of 4 slots and "1.0% of a 4.0% limit". Production persists hwm_v1 (ADR-0046), which charges the 17.92 give-back from the intra-trade equity peak; the operator decision ADR-0051 (net-from-start, 2026-08-04) says such a month shows 4 slots and 0%. The shadow metric robsond_budget_model_shadow_slots_delta reads 2 in production right now.
• ADR-0051's activation step was never run, and nothing on the dashboard would have followed the switch: the MONTHLY LIMIT gauge was computed from the HWM consumption regardless of the active model, so a flip would have shown 4 slots next to a 1.0% gauge.
• This PR makes /status and the card model-aware (ADR-0051 rollout step 3) and adds the activation runbook (step 4). It does not switch the model; that is the operator's guarded UPDATE monthly_state, documented, no restart needed.

Review round (Codex gpt-6.1 xhigh, on the branch)

First verdict: code checks passed (no consumer breaks on the null HWM fields, every monthly_state insert path inherits the model, no cache, rollback resumes from the true peak); three P1 and three P2 on the runbook/policy. Third commit answers them:

• Non-expanding basis now enforced in code (ADR-0051 §1): MonthlyBudgetModel::allows_capital_base_change withholds capital_base increases under net-from-start in both recalibration paths (ledger-confirmed TRANSFER, manual drift); decreases still apply; HWM unchanged. Unit-tested in robson-domain.
• Runbook gated on policy: step 0 stops unless the operator has approved the new "Activation exceptions" section of ADR-0051 (marked PENDING OPERATOR APPROVAL; it lists funding-outside-governed-net, Entering cancel, the August ledger gap, each with its bound). Nothing is waived by this PR.
• Settlement gate: direct ledger SQL (unmatched of any age must be 0), the month's out-of-band sum must stay under 10% of remaining budget, and month_governed_realized_net is cross-checked against the closed-position projection.
• P2s: MonthlyHalt latch check added; shadow-delta expectation corrected (metric stays slots_nfs − slots_hwm); first-entry validation distinguishes Armed (no reservation) from Entering/Active.

Rounds 2 and 3 (commits 4 and 5): the settlement-gap SQL selects funding by type (the matcher marks FUNDING_FEE rows matched), the slots formula uses monthly_budget_remaining directly, and ledger freshness is checked against the exchange's income history instead of the position-reconciliation metric. An in-memory attribution of withheld deposits in the drift scan was tried and removed on review: it could mask a later genuine withdrawal and did not survive restarts. Accepted, documented consequence: after an intra-month deposit under net-from-start the idle drift scan warns every cycle until the month boundary (fail-loud); the persisted design is #242 and the operating constraint until then is no intra-month deposits under net-from-start.

The PR leaves draft when the operator decides on the ADR-0051 "Activation exceptions" amendment.

Changes

• Key changes in this PR:
  • robsond/src/api.rs: new monthly_budget_utilization_pct (consumed under the active model, % of the 4% budget); month_peak_net and monthly_giveback_pct become Option and are served only while hwm_v1 is persisted (null under net-from-start, ADR-0051 §4). month_equity_net stays as informational mark-to-market. Slots, remaining budget and halt were already model-aware.
  • frontend/src/lib/presentation/budget.ts: budgetModelKind() (net_from_start | hwm | legacy) and deriveBudgetView prefers the utilization field; BudgetView.model exposed.
  • frontend/.../dashboard/+page.svelte: MONTHLY LIMIT copy per model ("Net governed loss since month start · Profits do not raise the limit" with net / reserved / left; HWM keeps peak / now; legacy unchanged).
  • frontend/src/lib/api/robson.ts: monthly_budget_model, monthly_budget_utilization_pct, month_governed_realized_net, monthly_net_loss_consumed, monthly_open_risk_reserved, monthly_budget_amount typed and normalized (null on older backends).
  • docs/runbooks/activate-net-from-start-budget.md (+ README index): preconditions (flat account, unmatched_income_count == 0, shadow check), guarded UPDATE for the current month, validation, rollback, accepted gaps (funding excluded from governed net; Entering cancel).
  • robson-domain/src/policy.rs, robsond/src/income_ledger.rs, robsond/src/reconciliation_worker.rs: non-expanding basis under net-from-start.
  • ADR-0051 status note and "Activation exceptions" (pending approval); CHANGELOG.

Tests

• How to verify:
  • cargo test -p robson-domain -p robsond --features robsond/postgres (container, rust 1.92) — 170 + 362 passed; clippy -D correctness -D suspicious clean; cargo +nightly-2026-08-22 fmt --check clean
  • cd frontend && npx vitest run — 133 passed (budget.test.ts 12); svelte-check 0 errors
• Added/updated tests:
  • robsond/src/api.rs status test asserts the HWM outputs are Some under hwm_v1 and utilization mirrors active consumption.
  • robson-domain/src/policy.rs: allows_capital_base_change under both models.
  • frontend/tests/unit/budget.test.ts: production payload of 2026-10-15 under both models, model-kind detection, and the guarantee that the gross-loss fallback is never used once utilization is reported (it would read 49.6% on a month that is net +83.50).

Migrations

• No schema changes (the monthly_budget_model column and CHECK exist since migration 25)

Backward Compatibility

• /status JSON: two fields may now be null (month_peak_net, monthly_giveback_pct), only after the operator switches the model. The frontend on main already types them as number | null and robson-cli does not read them. New field is additive.
• Deploy order: frontend and daemon can go in any order; the behaviour only changes when the runbook is executed, which requires both to be deployed (the runbook checks for monthly_budget_utilization_pct).
• Merging the daemon part restarts the pod: merge with an empty book (it is empty now).

Security & Data

• No secrets. No new external calls. The runbook runs SQL through kubectl exec on the prod Postgres pod with the operator's kubeconfig.

Checklist

• Scope is focused and documented
• Code follows project conventions (see docs/DEVELOPER.md)
• Migrations created (if needed) and rationale explained
• Tests added/updated and passing locally
• Docs updated (runbook, ADR-0051, CHANGELOG)

🤖 Generated with Claude Code