feat: implement asset snapshot and manual asset read model

docs/interface-contract.md

@@ -5,7 +5,7 @@
 - Status: governed
 - Owner: Jarca / project maintainer
 - Last Updated (KST): 2026-06-30
-- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007
+- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007, BAT-008
 
 ## Project Summary
 - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
@@ -26,6 +26,7 @@
 - Accounts: `create_ledger_account`, `list_ledger_accounts`, `update_ledger_account`; account payloads include additive `liquidity_bucket` for asset-liquidity reporting.
 - Transactions: `create_ledger_transaction`, `list_ledger_transactions`, `update_ledger_transaction`, `delete_ledger_transaction`
 - Budgets/reports: `create_ledger_budget`, `list_ledger_budgets`, monthly/category/fixed/budget/investable reports, `get_asset_liquidity_report`
+- Asset valuation reads: `list_manual_assets`, `get_asset_snapshot_report`, `get_net_worth_timeseries`; these are read-only in BAT-008 and use the same valuation policy as the dashboard.
 - Imports: KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, CSV preview/import where implemented
 - Categories/rules: category CRUD, rule CRUD, categorization preview/apply, uncategorized summaries
 - Reconciliation: cross-account preview/run/review queue, self-transfer candidates/linking, cancel-original candidates/linking
@@ -72,6 +73,14 @@
 | --- | --- | --- | --- | --- |
 | 1.0 | 2026-06-30 | Initial governed baseline | dcy-007 / REQ-007 / BAT-007 | Formalizes compatibility governance without exposing runtime version fields or changing success payload shapes. |
 
+### Asset Valuation Read Tools
+- `list_manual_assets(active_only=true)` returns `success`, `manual_assets`, `count`, and `valuation_policy`. Each item exposes `name`, `valuation_amount`, `valuation_date`, `liquidity_bucket`, `source_note`, `memo`, and `authority_source='manual_assets'`.
+- `get_asset_snapshot_report(basis_date='')` returns `success`, `basis_date`, `source`, `snapshot_count`, `buckets`, `total_assets`, `total_liabilities`, `net_worth`, `included_items`, `excluded_items`, and `valuation_policy`.
+  - If `asset_snapshots` rows exist for `basis_date`, `source='asset_snapshots'` and values come from stored snapshot rows.
+  - If no snapshot rows exist, `source='live_authority'` and the report reads `accounts.last_balance` plus active `manual_assets`.
+- `get_net_worth_timeseries(start_date='', end_date='', months=12)` returns `success`, requested date bounds, `points`, `count`, and `valuation_policy`; each point contains `basis_date`, `total_assets`, `total_liabilities`, `net_worth`, `source`, and `item_count`.
+- Contract impact: additive minor. Existing success payloads are preserved; `get_asset_liquidity_report` gains optional explanatory fields (`manual_assets`, `manual_asset_count`, `included_items`, `excluded_items`, `valuation_policy`) while preserving existing keys.
+
 ## Interface: CI Required-Check Contract
 - Required-check source of truth in code: `.github/workflows/ci.yml` job names are stable and must be mirrored by repository branch protection settings.
 - Required-check default set for PR/push merge blocking: `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, `lint`.
@@ -111,7 +120,8 @@
 - Rule page should support create/edit/delete and condition fields `amount_min`, `amount_max`, `day_of_month`.
 - Dialog-based triage actions should avoid losing context where possible.
 - Account page should display/edit `statement_status` and show a minimal manual balance reconciliation report without adding an automatic schedule or dedicated workbench.
-- Account page should display/edit `liquidity_bucket`; overview uses it with `last_balance` for asset liquidity/composition/debt/net-worth sections.
+- Account page should display/edit `liquidity_bucket`; overview uses the shared service valuation report for asset liquidity/composition/debt/net-worth sections.
+- Overview asset/net-worth display must keep the REQ-005 account-only fallback when `manual_assets`/`asset_snapshots` are empty, and may additionally show manual asset rows when present.
 - Overview top priority is KST current-month actual income/expense/net cashflow/savings rate based on `transaction_date` and `cashflow_kind`.
 - UI/dashboard-impacting batches require browser screenshot/snapshot evidence from synthetic/validation DBs. Non-UI batches may omit browser evidence, and docs-only batches do not require it.
 
@@ -129,7 +139,7 @@
 - Broad mutation workflows should capture metadata-only DB status and backup evidence before/after risky operations.
 - Restore execution is limited to script/runbook workflows and explicit approval, not MCP tools.
 - Manual balance reconciliation is preview/report-first. `REVIEW_NEEDED` suggests manual decision values (`계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`) but does not auto-confirm mutations.
-- Asset liquidity reporting is account-based: `liquidity_bucket='loan'` is debt/net-worth only, and missing `last_balance` rows must not be inferred from transaction totals.
+- Asset liquidity reporting uses the shared valuation policy: account-backed values from `accounts.last_balance`, non-transaction assets/liabilities from `manual_assets`, `loan` as debt/net-worth only, and missing values excluded with explanation rather than inferred from transaction totals.
 - Browser evidence screenshots/snapshots must use synthetic or validation DBs only and must not include real account identifiers, source financial filenames, passwords, or raw payloads.
 - Financial data and passwords are sensitive runtime inputs and should not be committed.
 
@@ -137,6 +147,7 @@
 - Formal MCP response contract versioning is defined for version `1.0`; full tool-surface snapshot coverage remains a future expansion beyond the representative BAT-007 scope.
 - Browser-level UI evidence criteria are captured in REQ-004 and remain local evidence rather than a required CI gate unless a future REQ changes that policy.
 - CI tests/lint required-check contract is defined for the six stable jobs listed above; actual branch protection enforcement remains an operator-managed repository setting.
+- BAT-008 adds read-only asset valuation MCP tools. Mutation MCP for manual asset CRUD or snapshot creation remains out of scope/future work.
 
 ## Change Log
 - 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
@@ -145,3 +156,4 @@
 - 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence 산출물과 UI evidence gate 규칙 추가.
 - 2026-06-29 KST: REQ-005/BAT-005 기준으로 account `liquidity_bucket`, `get_asset_liquidity_report`, dashboard operations hub contract 추가.
 - 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 MCP response contract `1.0` governance, representative contract-regression scope, `ruff` lint, six-job required-check contract를 추가.
+- 2026-06-30 KST: REQ-009/REQ-010/BAT-008 기준으로 `list_manual_assets`, `get_asset_snapshot_report`, `get_net_worth_timeseries` read MCP contract와 dashboard valuation alignment 규칙을 추가.