Skip to content

ADR-0051: persist budget-excluded wallet deltas so withheld basis increases stay coherent with drift attribution and restarts #242

Open

Description

@ldamasio

Context

#237 enforces ADR-0051 §1 (non-expanding monthly budget basis): under net_from_start_non_expanding_v1, a confirmed deposit or a reconciled manual gain no longer raises capital_base intra-month (MonthlyBudgetModel::allows_capital_base_change, applied in income_ledger.rs::recalibrate_from_confirmed_transfers and reconciliation_worker.rs manual-drift path).

Consequence (Codex review of #237, rounds 2 and 3): the wallet then sits above capital_base + robson_month_net by the withheld amount, so the idle pure-financial-drift scan (reconciliation_worker.rs, "Pure financial account drift detected") warns on every cycle until the month boundary re-snapshots the basis. An in-memory attribution scalar was tried in #237 and removed again because it could mask genuine drift (withheld deposit followed by an unexplained withdrawal of the same size), survived basis resets, and could not be rebuilt after a restart for manual gains.

Proposed design

  • New typed event CapitalBaseIncreaseWithheld { year, month, previous_capital_base, candidate_capital_base, wallet_balance, reason, evidence } emitted by both recalibration paths instead of returning silently.
  • Projection column monthly_state.budget_excluded_wallet_delta NUMERIC(20,8) NOT NULL DEFAULT 0 (migration), accumulated by the projector from that event; reset by MonthBoundaryReset (new row), reduced by evidenced reversals (a confirmed withdrawal matched by the ledger) and by any applied CapitalBaseRecalibrated.
  • Drift baseline becomes capital_base + robson_month_net + budget_excluded_wallet_delta; /status exposes the delta so the operator sees why WALLET BALANCE and capital_base diverge.
  • ADR-0051 §1 also allows deposits to update sizing capital without expanding the budget; decide whether sizing should follow the wallet (separate sizing basis) or stay on capital_base as today.

Until then

Behaviour is fail-loud, not masking: the recurring warning is expected after an intra-month deposit under net-from-start and is documented in docs/runbooks/activate-net-from-start-budget.md. Under hwm_v1 nothing changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions