# BAT-009 Design

## Schema and persistence design

- Reuse `manual_assets` / `asset_snapshots` tables from BAT-008 and extend them only additively for write workflow metadata as needed.
- `manual_assets` write lifecycle must support create/update/deactivate without destroying prior snapshot traceability.
- `asset_snapshots` remains append-only; correction runs add new rows/metadata rather than overwriting prior close rows.

## Write workflow design

- Service layer should expose:
  - manual asset create/update/deactivate helpers
  - snapshot preview helper that returns write-free totals/warnings
  - snapshot close helper that materializes authority-source rows for one `basis_date`
  - correction helper/metadata so same-date re-close is represented as a correction append, not overwrite
- Close path must preserve `source_type`, `source_id`, display name, valuation amount, `liquidity_bucket`, memo/reason metadata.

## MCP and contract design

- `server.py` should expose mutation MCP tools for manual asset CRUD and snapshot preview/close.
- Success/error envelopes must match dcy-007 contract conventions.
- Preview responses expose `source='live_authority'`, `is_closed_snapshot=false`; close responses expose `source='snapshot'`, `is_closed_snapshot=true`.
- Correction close responses must identify that a correction run occurred.

## Dashboard/operator UX design

- `dashboard/app.py` should provide manual asset create/edit/deactivate flows and a month-end close panel.
- Preview and close actions must be visually distinct.
- Screen text should clarify whether displayed values are live authority estimates or closed snapshot values.
- Correction history should be explainable at least through summary metadata/messages.

## Verification design

- Add targeted regression tests for:
  - manual asset update/deactivate lifecycle
  - snapshot preview side-effect freedom
  - append-only correction behavior for same `basis_date`
  - mutation MCP contract envelope coverage
  - dashboard/shared-helper fallback and source labeling
- Prefer temp DB + synthetic data + local Streamlit smoke only.