Implement BAT-009 manual asset CRUD and snapshot close

docs/interface-contract.md

@@ -4,8 +4,8 @@
 - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
 - Status: governed
 - Owner: Jarca / project maintainer
-- Last Updated (KST): 2026-06-30
-- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007, BAT-008
+- Last Updated (KST): 2026-07-01
+- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007, BAT-008, BAT-009
 
 ## Project Summary
 - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
@@ -26,7 +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.
+- Asset valuation reads/writes: `list_manual_assets`, `create_manual_asset`, `update_manual_asset`, `deactivate_manual_asset`, `preview_asset_snapshot_close`, `close_asset_snapshot`, `get_asset_snapshot_report`, `get_net_worth_timeseries`; these use the same valuation policy as the dashboard and preserve append-only snapshot correction semantics.
 - 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
@@ -73,13 +73,16 @@
 | --- | --- | --- | --- | --- |
 | 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
+### Asset Valuation Read/Mutation 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`.
+- `create_manual_asset`, `update_manual_asset`, and `deactivate_manual_asset` return dcy-007-compatible success/error envelopes. Mutation success includes the affected `manual_asset` payload or deactivation metadata; soft delete (`active=false`) is the default.
+- `preview_asset_snapshot_close(basis_date='')` returns `success`, `basis_date`, `source='live_authority'`, `is_closed_snapshot=false`, item lists, bucket totals, total assets/liabilities, net worth, and warnings. It is side-effect free.
+- `close_asset_snapshot(basis_date='', source_note='', memo='', correction_reason='')` writes item-level snapshot rows and returns `source='snapshot'`, `is_closed_snapshot=true`, `snapshot_run_id`, correction metadata, inserted count, totals, and warnings. If rows already exist for the same basis date, `correction_reason` is required and the close appends a correction run instead of overwriting.
+- `get_asset_snapshot_report(basis_date='')` returns `success`, `basis_date`, `source`, `is_closed_snapshot`, `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'`, `is_closed_snapshot=true`, and values come from the latest stored close run when run metadata exists.
+  - If no snapshot rows exist, `source='live_authority'`, `is_closed_snapshot=false`, 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.
+- 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, and BAT-009 adds new mutation/preview scopes to contract regression.
 
 ## 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.