# BAT-008 Design

## Schema and persistence design

- Add `manual_assets` as a first-class table for non-transaction-derived assets/liabilities.
- Add `asset_snapshots` as an append-only history table keyed by basis date plus evaluated item identity.
- Migrations remain additive/idempotent; existing ledger/account flows must continue to operate when both tables are empty.

## Authority-source and valuation design

- Account-backed assets use `accounts.last_balance` as the live authority source.
- Non-transaction assets/liabilities use `manual_assets` as the live authority source.
- `asset_snapshots` is a historical record layer, not a competing primary input source.
- Net worth formula remains: asset buckets (`cash`, `investment`, `deposit`, `real_estate`, `other`) minus `loan`; missing valuations are excluded, not inferred.

## Read model design

- Service layer should expose:
  - manual assets list/report helpers
  - basis-date asset snapshot read helpers
  - net-worth timeseries helpers
  - shared valuation/fallback helpers consumed by both MCP and dashboard
- Snapshot read responses must expose basis date, bucket totals, liabilities, net worth, and inclusion/exclusion explanation fields.
- Manual assets read responses must expose item name, value, basis date, `liquidity_bucket`, and memo/source metadata.

## Dashboard alignment design

- `dashboard/app.py` should consume the same valuation helpers as the MCP read tools.
- If no manual assets/snapshots exist, dashboard behavior must safely fall back to REQ-005 account-based display.
- Excluded/unvalued items should be explainable instead of silently counted.

## Verification design

- Add targeted regression tests for:
  - additive migration creation
  - manual asset persistence and retrieval
  - snapshot accumulation/read behavior
  - net-worth formula / exclusion policy
  - dashboard/MCP shared fallback behavior
- Prefer synthetic SQLite fixtures and temp DBs only.