Manual Valuation#

Manual Valuation is the UI-driven workflow that lets users update an asset's value for any given date. It operates through a two-step confirm-then-commit flow and is backed by the same Valuation / ReconciliationManager infrastructure used by Account Statement Reconciliation and Investment Account Reconciliation — but is distinct from both: it is triggered directly by the user through the web UI rather than by PDF-statement matching or API calls.

Scope: applies to all account types — depository, credit card, loan, property, vehicle, crypto, investment, and other asset/liability accounts 1.

The Valuation Model#

Valuation is an Entryable stored in the entries table. Its kind enum has three values 2:

Manual valuations always use kind: "reconciliation". Display names are generated by Valuation::Name based on both the kind and the account type.

Confirm-Then-Commit Flow#

The web UI enforces a preview step before any write is committed. Routes 3:

POST /valuations/confirm_create → ValuationsController#confirm_create
POST /valuations/:id/confirm_update → ValuationsController#confirm_update
POST /valuations → ValuationsController#create
PATCH /valuations/:id → ValuationsController#update

Create path:

1. User submits amount + date → confirm_create runs a dry-run reconciliation via account.create_reconciliation(balance:, date:, dry_run: true) 4. The dry run returns a ReconciliationResult without saving.
2. The result is rendered in _confirmation_contents.html.erb, showing the projected new balance (and cash/holdings split for investment accounts).
3. User confirms → create calls account.create_reconciliation(balance:, date:) for real 5, then redirects to the account page.

Update path: mirrors create — confirm_update dry-runs account.update_reconciliation(@entry, ..., dry_run: true) 6, then update commits 7. Notes can be updated independently without triggering reconciliation 8.

ReconciliationManager — Core Logic#

Account::Reconcileable is a concern mixed into Account that exposes create_reconciliation / update_reconciliation and delegates to Account::ReconciliationManager#reconcile_balance.

reconcile_balance does the following 9:

1. Snapshot old balance for the date from the balances table.
2. Prepare valuation — finds the existing Valuation entry for that date, or builds a new one with kind: "reconciliation" 10.
3. Save (skipped on dry_run: true).
4. Compute contribution — the delta between the new amount and the prior balance, fed to GoalPledge::Reconciler 11. Investment accounts use the transfer pledge kind, so the delta is not treated as a deposit.
5. Enqueue sync via sync_later, which triggers Balance::ForwardCalculator to reproject balance history using the new valuation as an anchor point.

Returns a ReconciliationResult struct with old_balance, new_balance, old_cash_balance, new_cash_balance, and success? / error_message fields 12.

Investment accounts: derived_cash_balance preserves existing holdings by computing new_cash_balance = total_balance − existing_non_cash_balance 13. The confirmation UI surfaces this split 14.

Key Files#

Related Systems#

• Account Statement Reconciliation — compares uploaded PDF/CSV statements against the ledger; also uses ReconciliationManager to write anchor Valuation entries, but is driven by statement ingestion rather than direct user input.
• Investment Account Reconciliation — REST API path (POST /api/v1/valuations) for setting portfolio total; shares ReconciliationManager but has no confirm step. See the Investment Account Reconciliation article.
• Balance History / ForwardCalculator — explains how Valuation anchor points override the calculated balance on a given date. See the Balance History System article.