fix: address account valuation review findings

tests/test_valuation_contract_docs.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).parents[1]
+
+
+def _text(relative_path: str) -> str:
+    return (ROOT / relative_path).read_text(encoding="utf-8")
+
+
+def test_data_model_documents_cache_authority_and_legacy_basis_migration() -> None:
+    data_model = _text("docs/data-model.md")
+
+    required_contract = (
+        "`last_balance` is the current cache value",
+        "`last_balance_basis_date`",
+        "`last_synced_at` is the execution/sync timestamp",
+        "imports and account writes advance the account cache",
+        "`account_valuations` is the historical authority",
+        "older evidence never rolls back the current cache",
+        "additive migration",
+        "legacy rows with unknown basis remain unknown; no inference",
+    )
+    for marker in required_contract:
+        assert marker in data_model, marker
+
+
+def test_interface_contract_documents_public_valuation_enums_validation_and_mapping() -> None:
+    interface = _text("docs/interface-contract.md")
+
+    assert "actual enums in source" not in interface
+    required_contract = (
+        "source_type: `manual`, `import`, `account_write`, `reconciliation`, `snapshot`",
+        "verification_status: `verified`, `unverified`, `rejected`",
+        "valuation_kind: `balance`, `cash_balance`, `total_value`, `loan`, `loan_balance`",
+        "representative_liability_definition: `principal_only`, `principal_interest_fees`",
+        "loan accounts require representative_liability_definition for `loan`, `loan_balance`, and `balance` aliases",
+        "legacy valuation-kind aliases remain accepted and map to the canonical purpose",
+        "validation failure returns `validation_error` and performs no write",
+        "loan valuations map to liabilities and non-loan valuations map to assets",
+    )
+    for marker in required_contract:
+        assert marker in interface, marker