[verified] Implement account valuation history for issue 12

jarca_ledger_mcp/adapters/mcp/server.py

@@ -117,6 +117,26 @@ def update_ledger_account(account_id: str, name: str | None = None, type: str |
     return contracts.update_ledger_account(account_id, name=name, type=type, institution=institution, currency=currency, active=active, memo=memo, account_number_masked=account_number_masked, holder_name=holder_name, last_balance=last_balance, last_synced_at=last_synced_at, statement_status=statement_status, liquidity_bucket=liquidity_bucket)
 
 @mcp.tool()
+def register_account_valuation(account_id: str, basis_date: str, amount: int, currency: str = "KRW", valuation_kind: str = "balance", source_type: str = "manual", source_ref: str = "", verification_status: str = "unverified", memo: str = "", idempotency_key: str = "", as_of_at: str | None = None, timezone: str | None = None, cost_basis: int | None = None, net_contributed: int | None = None, reported_principal_kind: str | None = None, reported_principal_label: str | None = None, profit: int | None = None, return_rate: float | None = None, return_basis: str | None = None, principal: int | None = None, interest: int | None = None, fee: int | None = None, representative_liability_definition: str | None = None) -> dict:
+    """Register an append-only account valuation evidence row."""
+    return contracts.register_account_valuation(account_id, basis_date, amount, currency, valuation_kind, source_type, source_ref, verification_status, memo, idempotency_key, as_of_at, timezone, cost_basis, net_contributed, reported_principal_kind, reported_principal_label, profit, return_rate, return_basis, principal, interest, fee, representative_liability_definition)
+
+@mcp.tool()
+def list_account_valuations(account_id: str, include_rejected: bool = True) -> dict:
+    """List account valuation history."""
+    return contracts.list_account_valuations(account_id, include_rejected=include_rejected)
+
+@mcp.tool()
+def select_account_valuation(account_id: str, basis_date: str, as_of: bool = False, currency: str | None = None, valuation_kind: str | None = None) -> dict:
+    """Select an exact verified valuation or latest verified value as of a basis date."""
+    return contracts.select_account_valuation(account_id, basis_date, as_of=as_of, currency=currency, valuation_kind=valuation_kind)
+
+@mcp.tool()
+def correct_account_valuation(valuation_id: str, amount: int, correction_reason: str, idempotency_key: str = "", currency: str | None = None, valuation_kind: str | None = None, source_type: str | None = None, source_ref: str | None = None, verification_status: str | None = None, memo: str | None = None, as_of_at: str | None = None, timezone: str | None = None, cost_basis: int | None = None, net_contributed: int | None = None, reported_principal_kind: str | None = None, reported_principal_label: str | None = None, profit: int | None = None, return_rate: float | None = None, return_basis: str | None = None, principal: int | None = None, interest: int | None = None, fee: int | None = None, representative_liability_definition: str | None = None) -> dict:
+    """Append a reasoned correction to an account valuation."""
+    fields = {k: v for k, v in locals().items() if k not in {"valuation_id", "amount", "correction_reason", "idempotency_key"} and v is not None}
+    return contracts.correct_account_valuation(valuation_id, amount, correction_reason, idempotency_key=idempotency_key, **fields)
+@mcp.tool()
 def get_asset_liquidity_report() -> dict:
     """Return asset liquidity, debt, and net worth from shared account/manual valuation sources."""
     return contracts.get_asset_liquidity_report()
@@ -142,19 +162,19 @@ def deactivate_manual_asset(asset_id: str, hard_delete: bool = False) -> dict:
     return contracts.deactivate_manual_asset(asset_id, hard_delete=hard_delete)
 
 @mcp.tool()
-def preview_asset_snapshot_close(basis_date: str = "") -> dict:
+def preview_asset_snapshot_close(basis_date: str = "", selection_policy: str = "exact") -> dict:
     """Preview a month-end asset snapshot close without mutating the database."""
-    return contracts.preview_asset_snapshot_close(basis_date=basis_date)
+    return contracts.preview_asset_snapshot_close(basis_date=basis_date, selection_policy=selection_policy)
 
 @mcp.tool()
-def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str = "", correction_reason: str = "") -> dict:
+def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str = "", correction_reason: str = "", selection_policy: str = "exact", idempotency_key: str = "", allow_missing_exclusions: bool = False, allow_as_of_carry_forward: bool = False, approved_by: str = "", approval_reason: str = "", approval_reference: str = "") -> dict:
     """Close an asset snapshot for a basis date; same-date re-close appends correction rows."""
-    return contracts.close_asset_snapshot(basis_date=basis_date, source_note=source_note, memo=memo, correction_reason=correction_reason)
+    return contracts.close_asset_snapshot(basis_date=basis_date, source_note=source_note, memo=memo, correction_reason=correction_reason, selection_policy=selection_policy, idempotency_key=idempotency_key, allow_missing_exclusions=allow_missing_exclusions, allow_as_of_carry_forward=allow_as_of_carry_forward, approved_by=approved_by, approval_reason=approval_reason, approval_reference=approval_reference)
 
 @mcp.tool()
-def get_asset_snapshot_report(basis_date: str = "") -> dict:
+def get_asset_snapshot_report(basis_date: str = "", selection_policy: str = "exact") -> dict:
     """Return basis-date asset snapshot/net-worth report with live-authority fallback."""
-    return contracts.get_asset_snapshot_report(basis_date=basis_date)
+    return contracts.get_asset_snapshot_report(basis_date=basis_date, selection_policy=selection_policy)
 
 @mcp.tool()
 def get_net_worth_timeseries(start_date: str = "", end_date: str = "", months: int = 12) -> dict:
@@ -246,6 +266,11 @@ def get_monthly_cashflow_report(month: str = "") -> dict:
     """Return income, expenses, net cashflow, and savings rate for a month."""
     return contracts.get_monthly_cashflow_report(month)
 
+@mcp.tool()
+def get_monthly_settlement_summary(month: str = "") -> dict:
+    """Return the read-only monthly settlement summary."""
+    return contracts.get_monthly_settlement_summary(month)
+
 @mcp.tool()
 def get_category_spending_report(month: str = "", start_date: str = "", end_date: str = "", person: str = "") -> dict:
     """Return category/subcategory spending for a month or date range."""

jarca_ledger_mcp/adapters/mcp/tool_contracts.py

@@ -25,6 +25,11 @@ from ...service import (
     get_ledger_backup_status as get_ledger_backup_status,
     get_ledger_db_status as get_ledger_db_status,
     get_monthly_cashflow_report as get_monthly_cashflow_report,
+    get_monthly_settlement_summary as get_monthly_settlement_summary,
+    register_account_valuation as register_account_valuation,
+    list_account_valuations as list_account_valuations,
+    select_account_valuation as select_account_valuation,
+    correct_account_valuation as correct_account_valuation,
     get_net_worth_timeseries as get_net_worth_timeseries,
     get_review_operating_indicators as get_review_operating_indicators,
     get_uncategorized_merchant_summary as get_uncategorized_merchant_summary,
@@ -94,6 +99,11 @@ __all__ = [
     "get_ledger_backup_status",
     "get_ledger_db_status",
     "get_monthly_cashflow_report",
+    "get_monthly_settlement_summary",
+    "register_account_valuation",
+    "list_account_valuations",
+    "select_account_valuation",
+    "correct_account_valuation",
     "get_net_worth_timeseries",
     "get_review_operating_indicators",
     "get_uncategorized_merchant_summary",

jarca_ledger_mcp/adapters/streamlit/accounts_gateway.py

@@ -1,11 +1,19 @@
 from __future__ import annotations
 
 from ...service import (
+    correct_account_valuation as correct_account_valuation,
+    list_account_valuations as list_account_valuations,
     list_ledger_accounts as list_ledger_accounts,
+    register_account_valuation as register_account_valuation,
+    select_account_valuation as select_account_valuation,
     update_ledger_account as update_ledger_account,
 )
 
 __all__ = [
     "list_ledger_accounts",
     "update_ledger_account",
+    "register_account_valuation",
+    "list_account_valuations",
+    "select_account_valuation",
+    "correct_account_valuation",
 ]

jarca_ledger_mcp/application/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from . import accounts_write_services as _accounts_write_services
+from . import account_valuation_service as _account_valuation_service
 from . import asset_account_services as _asset_account_services
 from . import assets_service as _assets_service
 from . import budgets_write_services as _budgets_write_services
@@ -20,6 +21,7 @@ from . import uncategorized_workbench_service as _uncategorized_workbench_servic
 _EXPORT_MODULES = (
     shared,
     _accounts_write_services,
+    _account_valuation_service,
     _asset_account_services,
     _assets_service,
     _budgets_write_services,

jarca_ledger_mcp/application/account_valuation_service.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from datetime import date
+import math
+import re
+from typing import Any
+import sqlite3
+
+from .shared import db, fail, new_id, normalize_date, now_iso, ok, row_to_dict
+
+_VALID_STATUSES = {"verified", "unverified", "rejected"}
+_VALID_LOAN_DEFINITIONS = {"principal_only", "principal_interest_fees"}
+_VALID_CURRENCIES = {"KRW", "USD", "EUR", "JPY", "CNY", "GBP"}
+_VALID_KINDS = {"balance", "cash_balance", "total_value", "loan", "loan_balance"}
+_VALID_SOURCE_TYPES = {"manual", "import", "account_write", "reconciliation", "snapshot"}
+_COLUMNS = (
+    "amount", "currency", "valuation_kind", "source_type", "source_ref",
+    "verification_status", "memo", "as_of_at", "timezone", "cost_basis",
+    "net_contributed", "reported_principal_kind", "reported_principal_label",
+    "profit", "return_rate", "return_basis", "principal", "interest", "fee",
+    "representative_liability_definition",
+)
+
+
+def _valuation(row: Any) -> dict[str, Any]:
+    return row_to_dict(row)
+
+
+def _public_candidate(row: Any) -> dict[str, Any]:
+    return {k: row[k] for k in ("id", "basis_date", "currency", "valuation_kind", "verification_status")}
+
+
+def _strict_int(value: Any, field: str, allow_none: bool = True) -> int | None:
+    if value is None and allow_none:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be an integer")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and re.fullmatch(r"[+-]?\d+", value.strip()):
+        return int(value.strip())
+    raise ValueError(f"{field} must be an integer")
+
+
+def _strict_float(value: Any, field: str) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be a finite number")
+    try:
+        result = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{field} must be a finite number") from exc
+    if not math.isfinite(result):
+        raise ValueError(f"{field} must be a finite number")
+    return result
+
+
+def _validate_common(account_id: str, basis_date: str, amount: int, currency: str, verification_status: str, valuation_kind: str, source_type: str, representative_liability_definition: str | None) -> tuple[str, int, str, str, str, str | None] | dict[str, Any]:
+    if not isinstance(account_id, str) or not account_id.strip():
+        return fail("validation_error", "account_id must be non-empty")
+    try:
+        basis = normalize_date(basis_date)
+        amount_int = _strict_int(amount, "amount", allow_none=False)
+    except Exception as exc:
+        return fail("validation_error", str(exc))
+    currency_norm = (currency or "KRW").strip().upper()
+    if currency_norm not in _VALID_CURRENCIES:
+        return fail("validation_error", f"currency must be one of {sorted(_VALID_CURRENCIES)}")
+    status = (verification_status or "unverified").strip().lower()
+    if status not in _VALID_STATUSES:
+        return fail("validation_error", "verification_status must be verified, unverified, or rejected")
+    if not isinstance(valuation_kind, str):
+        return fail("validation_error", "valuation_kind must be a string")
+    kind = valuation_kind.strip().lower() or "balance"
+    if kind not in _VALID_KINDS:
+        return fail("validation_error", f"valuation_kind must be one of {sorted(_VALID_KINDS)}")
+    source = (source_type or "manual").strip().lower() or "manual"
+    if source not in _VALID_SOURCE_TYPES:
+        return fail("validation_error", f"source_type must be one of {sorted(_VALID_SOURCE_TYPES)}")
+    definition = representative_liability_definition.strip() if representative_liability_definition else None
+    if kind in {"loan", "loan_balance"} and definition not in _VALID_LOAN_DEFINITIONS:
+        return fail("validation_error", "loan valuation requires representative_liability_definition")
+    if kind not in {"loan", "loan_balance"} and definition is not None:
+        return fail("validation_error", "non-loan valuation cannot define representative liability")
+    if amount_int is None:
+        return fail("validation_error", "amount must be an integer")
+    return basis, amount_int, currency_norm, status, source, definition
+
+
+def record_account_valuation_candidate(conn: sqlite3.Connection, account_id: str, basis_date: str, amount: int, currency: str, source_type: str, source_ref: str, idempotency_key: str, memo: str = "") -> dict[str, Any]:
+    """Append an unverified candidate on a caller-owned transaction."""
+    account = conn.execute("SELECT currency FROM accounts WHERE id=?", (account_id,)).fetchone()
+    if account is None:
+        return fail("not_found", "account not found")
+    if (currency or "KRW").upper() != (account["currency"] or "KRW").upper():
+        return fail("validation_error", "valuation currency must match account currency")
+    basis = normalize_date(basis_date)
+    existing = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (account_id, idempotency_key)).fetchone()
+    if existing:
+        return ok(valuation=_valuation(existing), reused=True)
+    valuation_id = new_id("valuation")
+    conn.execute("""INSERT INTO account_valuations
+        (id,account_id,basis_date,amount,currency,valuation_kind,source_type,source_ref,verification_status,recorded_at,memo,idempotency_key)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?)""", (valuation_id, account_id, basis, int(amount), (currency or "KRW").upper(), "balance", source_type, source_ref or "", "unverified", now_iso(), memo, idempotency_key))
+    return ok(valuation=_valuation(conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone()), reused=False)
+
+
+def register_account_valuation(
+    account_id: str,
+    basis_date: str,
+    amount: int,
+    currency: str = "KRW",
+    valuation_kind: str = "balance",
+    source_type: str = "manual",
+    source_ref: str = "",
+    verification_status: str = "unverified",
+    memo: str = "",
+    idempotency_key: str = "",
+    as_of_at: str | None = None,
+    timezone: str | None = None,
+    cost_basis: int | None = None,
+    net_contributed: int | None = None,
+    reported_principal_kind: str | None = None,
+    reported_principal_label: str | None = None,
+    profit: int | None = None,
+    return_rate: float | None = None,
+    return_basis: str | None = None,
+    principal: int | None = None,
+    interest: int | None = None,
+    fee: int | None = None,
+    representative_liability_definition: str | None = None,
+    db_path: str | None = None,
+    supersedes_id: str | None = None,
+    correction_reason: str = "",
+) -> dict[str, Any]:
+    validated = _validate_common(account_id, basis_date, amount, currency, verification_status, valuation_kind, source_type, representative_liability_definition)
+    if isinstance(validated, dict):
+        return validated
+    basis, amount_int, currency_norm, status, source_norm, definition = validated
+    try:
+        optional_ints = {name: _strict_int(value, name) for name, value in {
+            "cost_basis": cost_basis, "net_contributed": net_contributed, "profit": profit,
+            "principal": principal, "interest": interest, "fee": fee}.items()}
+        return_rate = _strict_float(return_rate, "return_rate")
+    except (TypeError, ValueError) as exc:
+        return fail("validation_error", str(exc))
+    if (as_of_at is None) != (timezone is None):
+        return fail("validation_error", "as_of_at and timezone must be supplied together")
+    if as_of_at is not None:
+        try:
+            from datetime import datetime
+            parsed = datetime.fromisoformat(as_of_at)
+            if parsed.tzinfo is None:
+                return fail("validation_error", "as_of_at must include timezone offset")
+        except (TypeError, ValueError) as exc:
+            return fail("validation_error", f"invalid as_of_at: {exc}")
+    ts = now_iso()
+    values = (amount_int, currency_norm, (valuation_kind or "balance").strip().lower(), source_norm, source_ref or "", status, memo or "", as_of_at, timezone, optional_ints["cost_basis"], optional_ints["net_contributed"], reported_principal_kind, reported_principal_label, optional_ints["profit"], return_rate, return_basis, optional_ints["principal"], optional_ints["interest"], optional_ints["fee"], definition)
+    with db(db_path) as conn:
+        account = conn.execute("SELECT * FROM accounts WHERE id=?", (account_id,)).fetchone()
+        if account is None:
+            return fail("not_found", "account not found")
+        if currency_norm != (account["currency"] or "KRW").upper():
+            return fail("validation_error", "valuation currency must match account currency")
+        if (valuation_kind or "balance").strip().lower() in {"loan", "loan_balance"} and str(account["type"]).lower() != "loan":
+            return fail("validation_error", "loan valuation kind requires a loan account")
+        if idempotency_key:
+            existing = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (account_id, idempotency_key)).fetchone()
+            if existing:
+                current = _valuation(existing)
+                incoming = dict(zip(_COLUMNS, values))
+                incoming.update({"account_id": account_id, "basis_date": basis, "supersedes_id": supersedes_id, "correction_reason": correction_reason or ""})
+                comparable = set(incoming) - {"id", "recorded_at"}
+                if all(current.get(k) == v for k, v in incoming.items() if k in comparable):
+                    return ok(valuation=current, reused=True)
+                return fail("idempotency_conflict", "idempotency_key already has a different payload", valuation=current)
+        valuation_id = new_id("valuation")
+        try:
+            conn.execute("""INSERT INTO account_valuations
+            (id,account_id,basis_date,amount,currency,valuation_kind,source_type,source_ref,verification_status,recorded_at,memo,idempotency_key,supersedes_id,correction_reason,as_of_at,timezone,cost_basis,net_contributed,reported_principal_kind,reported_principal_label,profit,return_rate,return_basis,principal,interest,fee,representative_liability_definition)
+            VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""", (valuation_id, account_id, basis, *values[:6], ts, values[6], idempotency_key or "", supersedes_id, correction_reason, *values[7:]))
+        except sqlite3.IntegrityError as exc:
+            if supersedes_id:
+                return fail("correction_conflict", "valuation already has a correction")
+            return fail("idempotency_conflict", str(exc))
+        except Exception as exc:
+            return fail("validation_error", str(exc))
+        row = conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone()
+    return ok(valuation=_valuation(row), reused=False)
+
+
+def list_account_valuations(account_id: str, include_rejected: bool = True, db_path: str | None = None) -> dict[str, Any]:
+    where = "" if include_rejected else " AND verification_status <> 'rejected'"
+    with db(db_path) as conn:
+        rows = conn.execute(f"SELECT * FROM account_valuations WHERE account_id=?{where} ORDER BY basis_date, recorded_at, id", (account_id,)).fetchall()
+    values = [_valuation(row) for row in rows]
+    return ok(account_id=account_id, valuations=values, count=len(values))
+
+
+def select_account_valuation(account_id: str, basis_date: str, as_of: bool = False, currency: str | None = None, valuation_kind: str | None = None, db_path: str | None = None) -> dict[str, Any]:
+    try:
+        basis = normalize_date(basis_date)
+    except Exception as exc:
+        return fail("validation_error", str(exc))
+    with db(db_path) as conn:
+        clauses = ["account_id=?"]
+        params: list[Any] = [account_id]
+        if currency:
+            clauses.append("currency=?"); params.append(currency.strip().upper())
+        if valuation_kind:
+            clauses.append("valuation_kind=?"); params.append(valuation_kind.strip().lower())
+        rows = conn.execute(f"SELECT * FROM account_valuations WHERE {' AND '.join(clauses)} ORDER BY basis_date DESC, recorded_at DESC, id DESC", params).fetchall()
+        leaves = [r for r in rows if conn.execute("SELECT 1 FROM account_valuations WHERE supersedes_id=?", (r["id"],)).fetchone() is None]
+        verified = [r for r in leaves if r["verification_status"] == "verified" and r["basis_date"] <= basis]
+        exact = [r for r in verified if r["basis_date"] == basis]
+        # Candidates are evidence at or before the requested basis.  Exact
+        # selection only surfaces same-date unverified evidence; as-of
+        # selection surfaces unverified evidence newer than the selected
+        # verified value, while never looking into the future.
+        latest_verified_date = max((x["basis_date"] for x in verified), default="")
+        candidate = [
+            r for r in leaves
+            if r["verification_status"] != "verified"
+            and r["basis_date"] <= basis
+            and (r["basis_date"] == basis if not as_of else (not latest_verified_date or r["basis_date"] > latest_verified_date))
+        ]
+        matching = exact if not as_of else [r for r in verified if r["basis_date"] == latest_verified_date]
+        if len(matching) > 1:
+            return fail("ambiguous_valuation", "multiple verified valuation leaves match the scope")
+        row = matching[0] if matching else None
+    if row is None:
+        result = ok(account_id=account_id, basis_date=basis, valuation=None, carried_forward=False)
+        if candidate:
+            result["warning"] = "unverified_candidate"
+            result["unverified_candidates"] = [_public_candidate(item) for item in candidate]
+        return result
+    age = (date.fromisoformat(basis) - date.fromisoformat(row["basis_date"])).days
+    warning = "unverified_candidate" if candidate else ("carry_forward" if age else None)
+    result = ok(account_id=account_id, basis_date=basis, valuation=_valuation(row), carried_forward=bool(age), valuation_age_days=age, warning=warning)
+    if candidate:
+        result["unverified_candidates"] = [_public_candidate(item) for item in candidate]
+    return result
+
+
+def correct_account_valuation(valuation_id: str, amount: int, correction_reason: str, idempotency_key: str = "", db_path: str | None = None, **fields: Any) -> dict[str, Any]:
+    if not correction_reason or not correction_reason.strip():
+        return fail("validation_error", "correction_reason is required")
+    with db(db_path) as conn:
+        source = conn.execute("SELECT * FROM account_valuations WHERE id=?", (valuation_id,)).fetchone()
+        if source is None:
+            return fail("not_found", "valuation not found")
+        if idempotency_key:
+            prior = conn.execute("SELECT * FROM account_valuations WHERE account_id=? AND idempotency_key=?", (source["account_id"], idempotency_key)).fetchone()
+            if prior:
+                expected = {"amount": amount, "supersedes_id": valuation_id, "correction_reason": correction_reason.strip()}
+                expected.update({k: fields[k] for k in fields})
+                if all(prior[k] == v for k, v in expected.items() if k in prior.keys()):
+                    return ok(valuation=_valuation(prior), reused=True)
+                return fail("idempotency_conflict", "idempotency_key already has a different payload", valuation=_valuation(prior))
+        if conn.execute("SELECT 1 FROM account_valuations WHERE supersedes_id=?", (valuation_id,)).fetchone():
+            return fail("correction_conflict", "valuation already has a correction")
+    preserved = {name: fields[name] if name in fields else source[name] for name in (
+        "currency", "valuation_kind", "source_type", "source_ref", "verification_status", "memo", "as_of_at", "timezone",
+        "cost_basis", "net_contributed", "reported_principal_kind", "reported_principal_label", "profit", "return_rate", "return_basis", "principal", "interest", "fee", "representative_liability_definition")}
+    return register_account_valuation(
+        source["account_id"], source["basis_date"], amount,
+        **preserved,
+        idempotency_key=idempotency_key,
+        supersedes_id=valuation_id, correction_reason=correction_reason.strip(),
+        db_path=db_path,
+    )

jarca_ledger_mcp/application/accounts_write_services.py

@@ -1,66 +1,65 @@
 from __future__ import annotations
+from .shared import Any, VALID_ACCOUNT_TYPES, db, fail, new_id, normalize_liquidity_bucket, normalize_statement_status, now_iso, ok, row_to_dict
 
-from .shared import (
-    Any,
-    VALID_ACCOUNT_TYPES,
-    db,
-    fail,
-    new_id,
-    normalize_liquidity_bucket,
-    normalize_statement_status,
-    now_iso,
-    ok,
-    row_to_dict,
-)
+
+def _record_balance_candidate(conn: Any, account: dict[str, Any], balance: Any = None, synced: str | None = None) -> None:
+    balance = account.get("last_balance") if balance is None else balance
+    synced = account.get("last_synced_at") if synced is None else synced
+    if balance is None or not str(synced or ""):
+        return
+    try:
+        from .account_valuation_service import record_account_valuation_candidate
+        record_account_valuation_candidate(conn, account["id"], str(synced), int(balance), account.get("currency", "KRW"), "account_write", account.get("updated_at", ""), f"account-balance:{account['id']}:{str(synced)[:10]}:{balance}", "account balance write candidate")
+    except (ValueError, TypeError):
+        return
 
 
 def create_ledger_account(name: str, type: str = "bank", institution: str = "", currency: str = "KRW", active: bool = True, memo: str = "", account_number_masked: str = "", holder_name: str = "", last_balance: int | None = None, last_synced_at: str = "", statement_status: str = "unknown", liquidity_bucket: str = "other", db_path: str | None = None) -> dict[str, Any]:
-    if not name.strip():
-        return fail("validation_error", "account name is required")
-    if type not in VALID_ACCOUNT_TYPES:
-        return fail("validation_error", f"type must be one of {sorted(VALID_ACCOUNT_TYPES)}")
+    if not name.strip(): return fail("validation_error", "account name is required")
+    if type not in VALID_ACCOUNT_TYPES: return fail("validation_error", f"type must be one of {sorted(VALID_ACCOUNT_TYPES)}")
     try:
         statement_status_norm = normalize_statement_status(statement_status)
         liquidity_bucket_norm = normalize_liquidity_bucket(liquidity_bucket)
-    except Exception as e:
-        return fail("validation_error", str(e))
+    except Exception as e: return fail("validation_error", str(e))
     ts = now_iso(); account_id = new_id("acct")
     with db(db_path) as conn:
-        conn.execute("""INSERT INTO accounts(id,name,type,institution,currency,active,memo,account_number_masked,holder_name,last_balance,last_synced_at,statement_status,liquidity_bucket,created_at,updated_at)
-                      VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""", (account_id, name.strip(), type, institution, currency, int(active), memo, account_number_masked, holder_name, last_balance, last_synced_at, statement_status_norm, liquidity_bucket_norm, ts, ts))
+        conn.execute("INSERT INTO accounts(id,name,type,institution,currency,active,memo,account_number_masked,holder_name,last_balance,last_synced_at,statement_status,liquidity_bucket,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", (account_id,name.strip(),type,institution,currency.upper(),int(active),memo,account_number_masked,holder_name,last_balance,last_synced_at,statement_status_norm,liquidity_bucket_norm,ts,ts))
         row = conn.execute("SELECT * FROM accounts WHERE id=?", (account_id,)).fetchone()
-    return ok(account=row_to_dict(row))
+        account = row_to_dict(row)
+        _record_balance_candidate(conn, account)
+    return ok(account=account)
 
 
 def update_ledger_account(account_id: str, db_path: str | None = None, **fields: Any) -> dict[str, Any]:
-    allowed = {"name", "type", "institution", "currency", "active", "memo", "account_number_masked", "holder_name", "last_balance", "last_synced_at", "statement_status", "liquidity_bucket"}
-    updates: list[str] = []
-    params: list[Any] = []
-    for k, v in fields.items():
-        if k not in allowed or v is None:
-            continue
-        try:
-            if k == "type" and v not in VALID_ACCOUNT_TYPES:
-                return fail("validation_error", f"type must be one of {sorted(VALID_ACCOUNT_TYPES)}")
-            if k == "statement_status":
-                v = normalize_statement_status(str(v))
-            if k == "liquidity_bucket":
-                v = normalize_liquidity_bucket(str(v))
-            if k == "active":
-                v = int(bool(v))
-            if k == "last_balance" and v != "":
-                v = int(v)
-        except Exception as e:
-            return fail("validation_error", str(e))
-        updates.append(f"{k}=?")
-        params.append(v)
-    if not updates:
-        return fail("validation_error", "no fields to update")
-    updates.append("updated_at=?")
-    params.extend([now_iso(), account_id])
+    allowed = {"name","type","institution","currency","active","memo","account_number_masked","holder_name","last_balance","last_synced_at","statement_status","liquidity_bucket"}
     with db(db_path) as conn:
-        cur = conn.execute(f"UPDATE accounts SET {', '.join(updates)} WHERE id=?", params)
-        if cur.rowcount == 0:
-            return fail("not_found", "account not found")
+        current = conn.execute("SELECT * FROM accounts WHERE id=?", (account_id,)).fetchone()
+        if current is None: return fail("not_found", "account not found")
+        updates=[]; params=[]
+        for k,v in fields.items():
+            if k not in allowed or v is None: continue
+            try:
+                if k == "type" and v not in VALID_ACCOUNT_TYPES: return fail("validation_error", f"type must be one of {sorted(VALID_ACCOUNT_TYPES)}")
+                if k == "statement_status": v = normalize_statement_status(str(v))
+                if k == "liquidity_bucket": v = normalize_liquidity_bucket(str(v))
+                if k == "active": v = int(bool(v))
+                if k == "last_balance" and v != "": v = int(v)
+                if k == "currency": v = str(v).upper()
+            except Exception as e: return fail("validation_error", str(e))
+            updates.append(f"{k}=?"); params.append(v)
+        if not updates: return fail("validation_error", "no fields to update")
+        incoming_date = str(fields.get("last_synced_at") or current["last_synced_at"] or "")[:10]
+        stored_date = str(current["last_synced_at"] or "")[:10]
+        historical = bool(incoming_date and stored_date and incoming_date < stored_date)
+        candidate_balance = fields.get("last_balance", current["last_balance"])
+        candidate_date = fields.get("last_synced_at", current["last_synced_at"])
+        if historical:
+            kept=[(u,p) for u,p in zip(updates,params) if not u.startswith(("last_balance=","last_synced_at="))]
+            updates=[u for u,_ in kept]; params=[p for _,p in kept]
+        updates.append("updated_at=?"); params.extend([now_iso(), account_id])
+        conn.execute(f"UPDATE accounts SET {', '.join(updates)} WHERE id=?", params)
         row = conn.execute("SELECT * FROM accounts WHERE id=?", (account_id,)).fetchone()
-    return ok(account=row_to_dict(row))
+        account = row_to_dict(row)
+        if any(k in fields for k in ("last_balance", "last_synced_at")):
+            _record_balance_candidate(conn, account, candidate_balance, candidate_date)
+    return ok(account=account)

jarca_ledger_mcp/application/assets_service.py

@@ -1,5 +1,10 @@
 from __future__ import annotations
 
+import json
+import hashlib
+
+from .account_valuation_service import _public_candidate
+
 from .shared import (
     ASSET_BUCKETS,
     ASSET_BUCKET_ORDER,
@@ -29,19 +34,36 @@ def _valuation_policy() -> dict[str, Any]:
     }
 
 
-def _account_valuation_items(conn: sqlite3.Connection) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+def _evidence_state_hash(item: dict[str, Any]) -> str:
+    """Bind idempotency to evidence state without exposing sensitive text."""
+    fields = (
+        "source_type", "source_id", "name", "amount", "currency",
+        "liquidity_bucket", "authority_source", "valuation_id",
+        "valuation_date", "verification_status", "source_note", "memo",
+        "active", "carried_forward",
+    )
+    payload = {key: item.get(key) for key in fields}
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+    ).hexdigest()
+
+
+def _account_valuation_items(conn: sqlite3.Connection, basis_date: str = "", selection_policy: str = "exact") -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
     rows = conn.execute("SELECT * FROM accounts WHERE active=1 ORDER BY name").fetchall()
     included: list[dict[str, Any]] = []
     excluded: list[dict[str, Any]] = []
     invalid: list[dict[str, Any]] = []
     for row in rows:
         account = row_to_dict(row)
+        account_type = str(account.get("type") or "other").lower()
         raw_bucket = str(account.get("liquidity_bucket") or "other")
         try:
             bucket = normalize_liquidity_bucket(raw_bucket)
         except ValueError:
             bucket = "other"
             invalid.append({"id": account.get("id", ""), "name": account.get("name", ""), "liquidity_bucket": raw_bucket})
+        if account_type == "loan":
+            bucket = "loan"
         base = {
             "id": account.get("id", ""),
             "source_id": account.get("id", ""),
@@ -56,6 +78,62 @@ def _account_valuation_items(conn: sqlite3.Connection) -> tuple[list[dict[str, A
             "memo": account.get("memo", ""),
         }
         balance = account.get("last_balance")
+        if basis_date:
+            valuation_rows = conn.execute(
+                "SELECT * FROM account_valuations WHERE account_id=? AND currency=? ORDER BY basis_date DESC, recorded_at DESC, id DESC",
+                (account["id"], account.get("currency") or "KRW"),
+            ).fetchall()
+            leaves = [v for v in valuation_rows if conn.execute("SELECT 1 FROM account_valuations WHERE supersedes_id=?", (v["id"],)).fetchone() is None]
+            if account_type == "investment":
+                # Older imports recorded investment balances as cash_balance;
+                # keep that as a compatibility fallback after the canonical
+                # total_value/balance purposes.
+                purposes = ("total_value", "balance", "cash_balance")
+            elif account_type == "loan":
+                purposes = ("loan_balance", "loan", "balance")
+            else:
+                purposes = ("cash_balance", "balance")
+            selected = None
+            selected_purpose = None
+            candidate_rows = []
+            for purpose in purposes:
+                scoped = [v for v in leaves if v["valuation_kind"] == purpose]
+                if selection_policy == "exact":
+                    verified = [v for v in scoped if v["verification_status"] == "verified" and v["basis_date"] == basis_date]
+                else:
+                    eligible = [v for v in scoped if v["verification_status"] == "verified" and v["basis_date"] <= basis_date]
+                    latest = max((v["basis_date"] for v in eligible), default="")
+                    verified = [v for v in eligible if v["basis_date"] == latest]
+                if len(verified) > 1:
+                    invalid.append({**base, "reason": "ambiguous_valuation", "valuation_kind": purpose})
+                    verified = []
+                    break
+                if verified:
+                    selected, selected_purpose = verified[0], purpose
+                    break
+                candidate_rows.extend(v for v in scoped if v["verification_status"] != "verified" and v["basis_date"] <= basis_date and (v["basis_date"] == basis_date if selection_policy == "exact" else True))
+            if selected is None:
+                excluded.append({**base, "reason": "missing_verified_exact_valuation" if selection_policy == "exact" else "missing_verified_valuation", "unverified_candidates": [_public_candidate(v) for v in candidate_rows]})
+                continue
+            valuation = selected
+            if account_type == "loan" and (
+                selected_purpose not in {"loan", "loan_balance"}
+                or not valuation["representative_liability_definition"]
+            ):
+                excluded.append({
+                    **base,
+                    "reason": "missing_representative_liability_definition",
+                    "valuation_id": valuation["id"],
+                    "valuation_kind": selected_purpose,
+                    "valuation_date": valuation["basis_date"],
+                    "verification_status": valuation["verification_status"],
+                })
+                continue
+            balance = valuation["amount"]
+            base.update({"valuation_id": valuation["id"], "verification_status": "verified", "valuation_kind": selected_purpose, "valuation_date": valuation["basis_date"], "currency": valuation["currency"], "carried_forward": valuation["basis_date"] != basis_date})
+            if candidate_rows:
+                base["unverified_candidates"] = [_public_candidate(v) for v in candidate_rows if v["basis_date"] <= basis_date]
+
         if balance is None:
             excluded.append({**base, "reason": "missing_last_balance"})
             continue
@@ -64,13 +142,16 @@ def _account_valuation_items(conn: sqlite3.Connection) -> tuple[list[dict[str, A
     return included, excluded, invalid
 
 
-def _manual_asset_valuation_items(conn: sqlite3.Connection, active_only: bool = True) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+def _manual_asset_valuation_items(conn: sqlite3.Connection, active_only: bool = True, basis_date: str = "", selection_policy: str = "exact") -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     where = "WHERE active=1" if active_only else ""
     rows = conn.execute(f"SELECT * FROM manual_assets {where} ORDER BY name").fetchall()
     included: list[dict[str, Any]] = []
     excluded: list[dict[str, Any]] = []
     for row in rows:
         asset = row_to_dict(row)
+        if (asset.get("currency") or "KRW").upper() != "KRW":
+            excluded.append({"id": asset.get("id", ""), "source_id": asset.get("id", ""), "source_type": "manual_asset", "reason": "non_krw_without_fx", "currency": asset.get("currency")})
+            continue
         try:
             bucket = normalize_liquidity_bucket(asset.get("liquidity_bucket"))
         except ValueError:
@@ -88,6 +169,12 @@ def _manual_asset_valuation_items(conn: sqlite3.Connection, active_only: bool =
             "active": asset.get("active", True),
         }
         value = asset.get("valuation_amount")
+        if basis_date:
+            valuation_date = str(asset.get("valuation_date") or "")[:10]
+            if not valuation_date or valuation_date > basis_date or (selection_policy == "exact" and valuation_date != basis_date):
+                excluded.append({**base, "reason": "missing_exact_manual_asset_valuation" if selection_policy == "exact" else "future_or_unknown_manual_asset_valuation"})
+                continue
+            base["carried_forward"] = valuation_date != basis_date
         if value is None:
             excluded.append({**base, "reason": "missing_valuation_amount"})
             continue
@@ -96,26 +183,12 @@ def _manual_asset_valuation_items(conn: sqlite3.Connection, active_only: bool =
 
 
 def _snapshot_rows_for_latest_run(conn: sqlite3.Connection, basis_date: str) -> tuple[list[sqlite3.Row], dict[str, Any]]:
-    rows = conn.execute(
-        "SELECT rowid AS _rowid, * FROM asset_snapshots WHERE basis_date=? ORDER BY created_at ASC, name ASC",
-        (basis_date,),
-    ).fetchall()
-    if not rows:
-        return [], {}
-    run_rows = [row for row in rows if "snapshot_run_id" in row.keys() and row["snapshot_run_id"]]
-    if not run_rows:
-        return rows, {"snapshot_run_id": "", "is_correction": False, "correction_of_run_id": "", "correction_reason": "", "total_snapshot_rows_for_basis_date": len(rows)}
-    latest = sorted(run_rows, key=lambda row: (int(row["_rowid"]), row["closed_at"] or row["created_at"] or "", row["snapshot_run_id"] or ""))[-1]
-    latest_run_id = latest["snapshot_run_id"]
-    selected = [row for row in run_rows if row["snapshot_run_id"] == latest_run_id]
-    metadata = {
-        "snapshot_run_id": latest_run_id,
-        "is_correction": bool(latest["is_correction"]),
-        "correction_of_run_id": latest["correction_of_run_id"] or "",
-        "correction_reason": latest["correction_reason"] or "",
-        "closed_at": latest["closed_at"] or latest["created_at"] or "",
-        "total_snapshot_rows_for_basis_date": len(rows),
-    }
+    rows = conn.execute("SELECT rowid AS _rowid, * FROM asset_snapshots WHERE basis_date=? ORDER BY created_at ASC, name ASC", (basis_date,)).fetchall()
+    run = conn.execute("SELECT * FROM asset_snapshot_runs WHERE basis_date=? ORDER BY rowid DESC LIMIT 1", (basis_date,)).fetchone()
+    if not run:
+        return rows, {"snapshot_run_id": "", "is_correction": False, "correction_of_run_id": "", "correction_reason": "", "total_snapshot_rows_for_basis_date": len(rows)} if rows else {}
+    selected = [row for row in rows if row["snapshot_run_id"] == run["id"]]
+    metadata = {"snapshot_run_id": run["id"], "is_correction": bool(run["correction_of_run_id"]), "correction_of_run_id": run["correction_of_run_id"] or "", "correction_reason": run["correction_reason"] or "", "close_status": run["close_status"], "selection_policy": run["selection_policy"], "approved_by": run["approved_by"], "approved_at": run["approved_at"], "approval_reason": run["approval_reason"], "approval_reference": run["approval_reference"], "applied_evidence": json.loads(run["applied_evidence"] or "[]"), "excluded_evidence": json.loads(run["excluded_evidence"] or "[]"), "carried_evidence": json.loads(run["carried_evidence"] or "[]"), "closed_at": run["created_at"] or "", "total_snapshot_rows_for_basis_date": len(rows)}
     return selected, metadata
 
 
@@ -277,16 +350,18 @@ def deactivate_manual_asset(asset_id: str, hard_delete: bool = False, db_path: s
     return ok(**payload)
 
 
-def _snapshot_preview_from_conn(conn: sqlite3.Connection, basis: str) -> dict[str, Any]:
-    account_items, account_excluded, invalid_bucket_accounts = _account_valuation_items(conn)
-    manual_items, manual_excluded = _manual_asset_valuation_items(conn)
+def _snapshot_preview_from_conn(conn: sqlite3.Connection, basis: str, selection_policy: str = "exact") -> dict[str, Any]:
+    account_items, account_excluded, invalid_bucket_accounts = _account_valuation_items(conn, basis, selection_policy)
+    manual_items, manual_excluded = _manual_asset_valuation_items(conn, basis_date=basis, selection_policy=selection_policy)
     included = account_items + manual_items
     excluded = account_excluded + manual_excluded
     summary = _summarize_valuation_items(included, excluded)
     existing_rows = conn.execute("SELECT COUNT(*) FROM asset_snapshots WHERE basis_date=?", (basis,)).fetchone()[0]
     warnings: list[dict[str, Any]] = []
     for item in excluded:
-        warnings.append({"code": item.get("reason", "excluded_item"), "source_type": item.get("source_type", ""), "source_id": item.get("source_id", ""), "name": item.get("name", "")})
+        warnings.append({"code": item.get("reason", "excluded_item"), "source_type": item.get("source_type", ""), "source_id": item.get("source_id", ""), "currency": item.get("currency", "KRW")})
+        if item.get("unverified_candidates"):
+            warnings.append({"code": "unverified_candidate", "source_type": item.get("source_type", ""), "source_id": item.get("source_id", ""), "candidates": [{k: candidate.get(k) for k in ("id", "basis_date", "currency", "valuation_kind", "verification_status")} for candidate in item["unverified_candidates"]]})
     for item in included:
         item_date = str(item.get("valuation_date") or "")[:10]
         if item_date and item_date < basis:
@@ -307,17 +382,24 @@ def _snapshot_preview_from_conn(conn: sqlite3.Connection, basis: str) -> dict[st
     }
 
 
-def preview_asset_snapshot_close(basis_date: str = "", db_path: str | None = None) -> dict[str, Any]:
+def preview_asset_snapshot_close(basis_date: str = "", selection_policy: str = "exact", db_path: str | None = None) -> dict[str, Any]:
+    if selection_policy not in {"exact", "as_of"}:
+        return fail("validation_error", "selection_policy must be exact or as_of")
     try:
         basis = normalize_date(basis_date, default_today=True) if basis_date else current_kst_date().isoformat()
     except Exception as e:
         return fail("validation_error", str(e))
     with db(db_path) as conn:
-        preview = _snapshot_preview_from_conn(conn, basis)
+        preview = _snapshot_preview_from_conn(conn, basis, selection_policy)
+    preview["selection_policy"] = selection_policy
+    blocking = [w for w in preview["warnings"] if w.get("code", "").startswith(("missing_", "future_", "unknown_", "unverified", "ambiguous_", "stale_"))]
+    preview["close_status"] = "complete_exact" if selection_policy == "exact" and not blocking else "incomplete_draft"
     return ok(**preview)
 
 
-def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str = "", correction_reason: str = "", db_path: str | None = None) -> dict[str, Any]:
+def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str = "", correction_reason: str = "", selection_policy: str = "exact", idempotency_key: str = "", allow_missing_exclusions: bool = False, allow_as_of_carry_forward: bool = False, approved_by: str = "", approval_reason: str = "", approval_reference: str = "", db_path: str | None = None) -> dict[str, Any]:
+    if selection_policy not in {"exact", "as_of"}:
+        return fail("validation_error", "selection_policy must be exact or as_of")
     try:
         basis = normalize_date(basis_date, default_today=True) if basis_date else current_kst_date().isoformat()
     except Exception as e:
@@ -325,21 +407,39 @@ def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str
     ts = now_iso()
     run_id = new_id("snaprun")
     with db(db_path) as conn:
-        preview = _snapshot_preview_from_conn(conn, basis)
+        conn.execute("BEGIN IMMEDIATE")
+        preview = _snapshot_preview_from_conn(conn, basis, selection_policy)
+        missing_exclusions = [w for w in preview["warnings"] if w.get("code", "").startswith(("missing_", "future_", "unknown_", "unverified", "ambiguous_"))]
+        carried_items = [item for item in preview["included_items"] if item.get("carried_forward")]
+        conditional = bool(missing_exclusions or carried_items)
+        fingerprint_payload = {"basis_date": basis, "source_note": source_note, "memo": memo, "correction_reason": correction_reason, "selection_policy": selection_policy, "allow_missing_exclusions": allow_missing_exclusions, "allow_as_of_carry_forward": allow_as_of_carry_forward, "approved_by": approved_by, "approval_reason": approval_reason, "approval_reference": approval_reference, "included": [{**{k: i.get(k) for k in ("source_type", "source_id", "amount", "currency", "valuation_id", "valuation_date", "verification_status")}, "state_hash": _evidence_state_hash(i)} for i in preview["included_items"]], "excluded": [{**{k: i.get(k) for k in ("source_type", "source_id", "reason", "valuation_date", "verification_status")}, "state_hash": _evidence_state_hash(i)} for i in preview["excluded_items"]]}
+        fingerprint = hashlib.sha256(json.dumps(fingerprint_payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+        if missing_exclusions and (not allow_missing_exclusions or not approved_by.strip() or not approval_reason.strip() or not approval_reference.strip()):
+            return fail("conditional_approval_required", "missing exclusions require explicit approval metadata and allow_missing_exclusions")
+        if carried_items and (not allow_as_of_carry_forward or not approved_by.strip() or not approval_reason.strip() or not approval_reference.strip()):
+            return fail("conditional_approval_required", "conditional close requires explicit approval metadata and flags")
+        if idempotency_key:
+            existing_run = conn.execute("SELECT * FROM asset_snapshot_runs WHERE idempotency_key=?", (idempotency_key,)).fetchone()
+            if existing_run:
+                if existing_run["request_fingerprint"] == fingerprint:
+                    return ok(reused=True, snapshot_run_id=existing_run["id"], close_status=existing_run["close_status"], basis_date=basis)
+                return fail("idempotency_conflict", "snapshot close idempotency payload differs")
         included = preview["included_items"]
         latest_rows, latest_meta = _snapshot_rows_for_latest_run(conn, basis)
-        is_correction = bool(preview["existing_snapshot_row_count"])
+        # A conditional close may legitimately contain zero snapshot rows.
+        # The run record, not row count, is the authoritative close marker.
+        is_correction = bool(latest_meta.get("snapshot_run_id"))
         if is_correction and not correction_reason.strip():
-            return fail("validation_error", "correction_reason is required when closing a basis_date that already has snapshot rows", basis_date=basis, existing_snapshot_row_count=preview["existing_snapshot_row_count"])
-        correction_of_run_id = latest_meta.get("snapshot_run_id", "") if latest_rows else ""
+            return fail("validation_error", "correction_reason is required when closing a basis_date that already has a snapshot run", basis_date=basis, existing_snapshot_row_count=preview["existing_snapshot_row_count"])
+        correction_of_run_id = latest_meta.get("snapshot_run_id", "")
         snapshot_ids: list[str] = []
         for item in included:
             snapshot_id = new_id("snap")
             row_note = source_note or item.get("source_note", "") or "month-end close"
             row_memo = memo or item.get("memo", "")
             conn.execute(
-                """INSERT INTO asset_snapshots(id,basis_date,source_type,source_id,name,amount,currency,liquidity_bucket,valuation_source,source_note,memo,snapshot_run_id,correction_of_run_id,correction_reason,is_correction,closed_at,created_at)
-                   VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+                """INSERT INTO asset_snapshots(id,basis_date,source_type,source_id,name,amount,currency,liquidity_bucket,valuation_source,source_note,memo,snapshot_run_id,correction_of_run_id,correction_reason,is_correction,closed_at,valuation_id,selection_policy,verification_status,evidence_kind,exclusion_reason,created_at)
+                   VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
                 (
                     snapshot_id,
                     basis,
@@ -357,12 +457,24 @@ def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str
                     correction_reason.strip(),
                     int(is_correction),
                     ts,
+                    item.get("valuation_id", ""),
+                    selection_policy,
+                    item.get("verification_status", "unverified"),
+                    "carried_forward" if item.get("carried_forward") else "applied",
+                    "",
                     ts,
                 ),
             )
             snapshot_ids.append(snapshot_id)
-        report_items = _snapshot_items(conn, basis)
-        summary = _summarize_valuation_items(report_items, [])
+        summary = _summarize_valuation_items(included, [])
+        applied_evidence = [{k: item.get(k) for k in ("source_type", "source_id", "amount", "currency", "valuation_id", "valuation_date", "verification_status")} for item in included]
+        excluded_evidence = [{k: item.get(k) for k in ("source_type", "source_id", "reason", "currency")} for item in preview.get("excluded_items", [])]
+        carried_evidence = [{k: item.get(k) for k in ("source_type", "source_id", "amount", "currency", "valuation_id", "valuation_date", "verification_status")} for item in included if item.get("carried_forward")]
+        try:
+            conn.execute("INSERT INTO asset_snapshot_runs(id,basis_date,close_status,selection_policy,idempotency_key,approved_by,approved_at,approval_reason,approval_reference,correction_of_run_id,correction_reason,applied_evidence,excluded_evidence,carried_evidence,request_fingerprint,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", (run_id, basis, "conditional" if conditional else "complete_exact", selection_policy, idempotency_key, approved_by, ts if approved_by else "", approval_reason, approval_reference, correction_of_run_id, correction_reason.strip(), json.dumps(applied_evidence, ensure_ascii=False, sort_keys=True), json.dumps(excluded_evidence, ensure_ascii=False, sort_keys=True), json.dumps(carried_evidence, ensure_ascii=False, sort_keys=True), fingerprint, ts))
+        except sqlite3.IntegrityError as exc:
+            conn.rollback()
+            return fail("snapshot_conflict", "another snapshot close already owns this basis date", basis_date=basis, detail=str(exc))
     return ok(
         basis_date=basis,
         source="snapshot",
@@ -372,6 +484,8 @@ def close_asset_snapshot(basis_date: str = "", source_note: str = "", memo: str
         correction_reason=correction_reason.strip(),
         is_correction=is_correction,
         closed_at=ts,
+        close_status="conditional" if conditional else "complete_exact",
+        selection_policy=selection_policy,
         inserted_count=len(snapshot_ids),
         inserted_snapshot_ids=snapshot_ids,
         warnings=preview["warnings"],
@@ -402,12 +516,14 @@ def create_asset_snapshot(basis_date: str, source_type: str, source_id: str, nam
     return ok(asset_snapshot=row_to_dict(row))
 
 
-def get_asset_snapshot_report(basis_date: str = "", db_path: str | None = None) -> dict[str, Any]:
+def get_asset_snapshot_report(basis_date: str = "", selection_policy: str = "exact", db_path: str | None = None) -> dict[str, Any]:
+    if selection_policy not in {"exact", "as_of"}:
+        return fail("validation_error", "selection_policy must be exact or as_of")
     basis = normalize_date(basis_date, default_today=True) if basis_date else current_kst_date().isoformat()
     with db(db_path) as conn:
         rows, close_metadata = _snapshot_rows_for_latest_run(conn, basis)
         snapshots = _snapshot_items(conn, basis) if rows else []
-        if snapshots:
+        if close_metadata:
             summary = _summarize_valuation_items(snapshots, [])
             return ok(
                 basis_date=basis,
@@ -415,16 +531,20 @@ def get_asset_snapshot_report(basis_date: str = "", db_path: str | None = None)
                 is_closed_snapshot=True,
                 snapshot_count=len(snapshots),
                 close_metadata=close_metadata,
+                selection_policy=close_metadata.get("selection_policy", selection_policy),
+                close_status=close_metadata.get("close_status", "complete_exact"),
                 **summary,
             )
-        account_items, account_excluded, invalid_bucket_accounts = _account_valuation_items(conn)
-        manual_items, manual_excluded = _manual_asset_valuation_items(conn)
+        account_items, account_excluded, invalid_bucket_accounts = _account_valuation_items(conn, basis, selection_policy)
+        manual_items, manual_excluded = _manual_asset_valuation_items(conn, basis_date=basis, selection_policy=selection_policy)
     included = account_items + manual_items
     excluded = account_excluded + manual_excluded
     summary = _summarize_valuation_items(included, excluded)
     return ok(
         basis_date=basis,
         source="live_authority",
+        selection_policy=selection_policy,
+        close_status="incomplete_draft" if excluded else "complete_exact",
         is_closed_snapshot=False,
         snapshot_count=0,
         invalid_bucket_accounts=invalid_bucket_accounts,

jarca_ledger_mcp/application/imports_service.py

@@ -31,6 +31,13 @@ from .shared import (
     transaction_preview,
 )
 
+
+def _record_import_valuation_candidate(conn: Any, account_id: str, balance: Any, basis_date: str, source_hash: str) -> None:
+    if balance is None or not basis_date:
+        return
+    from .account_valuation_service import record_account_valuation_candidate
+    record_account_valuation_candidate(conn, account_id, basis_date, balance, "KRW", "import", source_hash, f"import-balance:{account_id}:{basis_date}:{source_hash}")
+
 def preview_ledger_csv_import(file_path: str, source: str = "generic", db_path: str | None = None) -> dict[str, Any]:
     path=Path(file_path).expanduser()
     if not path.exists():
@@ -211,10 +218,9 @@ def import_kb_bank_pdf(file_path: str, password: str, account_id: str = "", skip
                     raise
             conn.execute("UPDATE import_batches SET row_count=? WHERE id=?", (inserted, batch_id))
             if transactions:
-                conn.execute(
-                    "UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?",
-                    (transactions[-1].balance_after, ts, ts, linked_account_id),
-                )
+                conn.execute("UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?", (transactions[-1].balance_after, ts, ts, linked_account_id))
+            if transactions and transactions[-1].balance_after is not None:
+                _record_import_valuation_candidate(conn, linked_account_id, transactions[-1].balance_after, transactions[-1].transaction_date, source_hash)
     except ValueError as e:
         return fail("validation_error", str(e))
     except Exception as e:
@@ -677,10 +683,9 @@ def import_toss_bank_pdf(file_path: str, account_id: str = "", skip_duplicates:
                     raise
             conn.execute("UPDATE import_batches SET row_count=? WHERE id=?", (inserted, batch_id))
             if transactions:
-                conn.execute(
-                    "UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?",
-                    (transactions[-1].balance_after, ts, ts, linked_account_id),
-                )
+                conn.execute("UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?", (transactions[-1].balance_after, ts, ts, linked_account_id))
+            if transactions and transactions[-1].balance_after is not None:
+                _record_import_valuation_candidate(conn, linked_account_id, transactions[-1].balance_after, transactions[-1].transaction_date, source_hash)
     except ValueError as e:
         return fail("validation_error", str(e))
     except Exception as e:
@@ -902,10 +907,9 @@ def import_toss_securities_pdf(file_path: str, account_id: str = "", skip_duplic
                     raise
             conn.execute("UPDATE import_batches SET row_count=? WHERE id=?", (inserted, batch_id))
             if transactions:
-                conn.execute(
-                    "UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?",
-                    (transactions[-1].balance_after, ts, ts, linked_account_id),
-                )
+                conn.execute("UPDATE accounts SET last_balance=?, last_synced_at=?, updated_at=? WHERE id=?", (transactions[-1].balance_after, ts, ts, linked_account_id))
+            if transactions and transactions[-1].balance_after is not None:
+                _record_import_valuation_candidate(conn, linked_account_id, transactions[-1].balance_after, transactions[-1].transaction_date, source_hash)
     except ValueError as e:
         return fail("validation_error", str(e))
     except Exception as e:

jarca_ledger_mcp/application/monthly_settlement_service.py

@@ -64,6 +64,10 @@ def _source_coverage(
             "source": asset_report.get("source", ""),
             "is_closed_snapshot": bool(asset_report.get("is_closed_snapshot", False)),
             "net_worth": asset_report.get("net_worth"),
+            "close_status": asset_report.get("close_status", ""),
+            "warnings": asset_report.get("warnings", []),
+            "missing_items": [item for item in asset_report.get("excluded_items", []) if "missing" in str(item.get("reason", ""))],
+            "carried_items": [item for item in asset_report.get("included_items", []) if item.get("carried_forward")],
         },
     }
 
@@ -108,6 +112,7 @@ def get_monthly_settlement_summary(month: str = "", db_path: str | None = None)
         reports={
             "cashflow": cashflow_report,
             "budget": budget_report,
+            "assets": asset_report,
         },
         read_only=True,
     )

jarca_ledger_mcp/application/reconciliation_service.py

@@ -86,6 +86,24 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in
             effective_baseline = baseline_balance_int if baseline_balance_int is not None else account["last_balance"]
             effective_at = baseline_at_norm or account["last_synced_at"] or now_iso()
             calc = _account_balance_row(conn, account["id"], effective_at)
+            valuation = conn.execute(
+                """SELECT * FROM account_valuations v
+                     WHERE v.account_id=? AND v.verification_status='verified'
+                       AND v.basis_date<=?
+                       AND NOT EXISTS (
+                           SELECT 1 FROM account_valuations child
+                            WHERE child.supersedes_id=v.id
+                       )
+                     ORDER BY CASE v.valuation_kind
+                                  WHEN 'total_value' THEN 0
+                                  WHEN 'balance' THEN 1
+                                  WHEN 'cash_balance' THEN 2
+                                  ELSE 3
+                              END,
+                              v.basis_date DESC, v.recorded_at DESC, v.id DESC
+                     LIMIT 1""",
+                (account["id"], effective_at[:10]),
+            ).fetchone()
             if effective_baseline is None:
                 difference = None
                 ratio = None
@@ -94,6 +112,9 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in
                 difference = int(effective_baseline) - int(calc["calculated_balance"])
                 ratio = abs(difference) / abs(int(effective_baseline)) if int(effective_baseline) else None
                 status = "OK" if abs(difference) <= tolerance_int else "REVIEW_NEEDED"
+            if account["type"] == "investment" and valuation is not None:
+                status = "VALUATION_MANAGED"
+                difference = None
             items.append({
                 "account_id": account["id"],
                 "account_name": account["name"],
@@ -107,6 +128,9 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in
                 "reference_ratio_threshold": BALANCE_RECONCILIATION_REFERENCE_RATIO,
                 "difference_ratio": ratio,
                 "status": status,
+                "external_confirmed_value": int(valuation["amount"]) if valuation is not None else None,
+                "valuation_id": valuation["id"] if valuation is not None else "",
+                "valuation_kind": valuation["valuation_kind"] if valuation is not None else "",
                 "recommended_decisions": ["계좌이동", "실지출", "실수입", "투자이동", "분석제외", "확인필요"] if status == "REVIEW_NEEDED" else [],
                 "reconciliation_session": latest_sessions.get(account["id"]),
                 "review_status": latest_decisions.get(("reconciliation_account", account["id"]), {}).get("status", "pending"),

jarca_ledger_mcp/infrastructure/sqlite/migrations.py

@@ -98,10 +98,28 @@ def migrate_db(conn: sqlite3.Connection) -> None:
         "correction_reason": "TEXT NOT NULL DEFAULT ''",
         "is_correction": "INTEGER NOT NULL DEFAULT 0",
         "closed_at": "TEXT NOT NULL DEFAULT ''",
+        "valuation_id": "TEXT NOT NULL DEFAULT ''",
+        "selection_policy": "TEXT NOT NULL DEFAULT 'exact'",
+        "verification_status": "TEXT NOT NULL DEFAULT 'unverified'",
+        "evidence_kind": "TEXT NOT NULL DEFAULT 'applied'",
+        "exclusion_reason": "TEXT NOT NULL DEFAULT ''",
     })
     conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_basis_date ON asset_snapshots(basis_date)")
     conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_source ON asset_snapshots(source_type, source_id)")
     conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_run ON asset_snapshots(basis_date, snapshot_run_id, created_at)")
+    conn.execute("""CREATE TABLE IF NOT EXISTS asset_snapshot_runs (
+        id TEXT PRIMARY KEY, basis_date TEXT NOT NULL, close_status TEXT NOT NULL,
+        selection_policy TEXT NOT NULL DEFAULT 'exact', idempotency_key TEXT NOT NULL DEFAULT '',
+        approved_by TEXT NOT NULL DEFAULT '', approved_at TEXT NOT NULL DEFAULT '',
+        approval_reason TEXT NOT NULL DEFAULT '', approval_reference TEXT NOT NULL DEFAULT '',
+        correction_of_run_id TEXT NOT NULL DEFAULT '', correction_reason TEXT NOT NULL DEFAULT '',
+        applied_evidence TEXT NOT NULL DEFAULT '[]', excluded_evidence TEXT NOT NULL DEFAULT '[]',
+        carried_evidence TEXT NOT NULL DEFAULT '[]', request_fingerprint TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL
+    )""")
+    _add_missing_columns(conn, "asset_snapshot_runs", {"request_fingerprint": "TEXT NOT NULL DEFAULT ''"})
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_idempotency ON asset_snapshot_runs(idempotency_key) WHERE idempotency_key <> ''")
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_initial_basis ON asset_snapshot_runs(basis_date) WHERE correction_of_run_id = ''")
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_correction_parent ON asset_snapshot_runs(correction_of_run_id) WHERE correction_of_run_id <> ''")
     conn.execute("""CREATE TABLE IF NOT EXISTS review_decisions (
         id TEXT PRIMARY KEY,
         target_type TEXT NOT NULL,
@@ -136,6 +154,22 @@ def migrate_db(conn: sqlite3.Connection) -> None:
     )""")
     conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_reconciliation_sessions_account_basis ON reconciliation_sessions(account_id, basis_date)")
     conn.execute("CREATE INDEX IF NOT EXISTS idx_reconciliation_sessions_status ON reconciliation_sessions(status, closed_at)")
+    conn.execute("""CREATE TABLE IF NOT EXISTS account_valuations (
+        id TEXT PRIMARY KEY, account_id TEXT NOT NULL REFERENCES accounts(id), basis_date TEXT NOT NULL,
+        amount INTEGER NOT NULL, currency TEXT NOT NULL DEFAULT 'KRW', valuation_kind TEXT NOT NULL DEFAULT 'balance',
+        source_type TEXT NOT NULL DEFAULT 'manual', source_ref TEXT NOT NULL DEFAULT '',
+        verification_status TEXT NOT NULL DEFAULT 'unverified', recorded_at TEXT NOT NULL,
+        memo TEXT NOT NULL DEFAULT '', idempotency_key TEXT NOT NULL DEFAULT '',
+        supersedes_id TEXT REFERENCES account_valuations(id), correction_reason TEXT NOT NULL DEFAULT '',
+        as_of_at TEXT, timezone TEXT, cost_basis INTEGER, net_contributed INTEGER,
+        reported_principal_kind TEXT, reported_principal_label TEXT, profit INTEGER,
+        return_rate REAL, return_basis TEXT, principal INTEGER, interest INTEGER, fee INTEGER,
+        representative_liability_definition TEXT
+    )""")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_account_valuations_account_date ON account_valuations(account_id, basis_date, recorded_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_account_valuations_status_date ON account_valuations(verification_status, basis_date)")
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_account_valuations_idempotency ON account_valuations(account_id, idempotency_key) WHERE idempotency_key <> ''")
+    conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_account_valuations_single_correction ON account_valuations(supersedes_id) WHERE supersedes_id IS NOT NULL")
     conn.execute("INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', ?)", (SCHEMA_VERSION,))
 
 

jarca_ledger_mcp/infrastructure/sqlite/schema.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-SCHEMA_VERSION = "11"
+SCHEMA_VERSION = "12"
 
 SCHEMA_SQL = """
 PRAGMA journal_mode=WAL;
@@ -163,11 +163,38 @@ CREATE TABLE IF NOT EXISTS asset_snapshots (
     correction_reason TEXT NOT NULL DEFAULT '',
     is_correction INTEGER NOT NULL DEFAULT 0,
     closed_at TEXT NOT NULL DEFAULT '',
+    valuation_id TEXT NOT NULL DEFAULT '',
+    selection_policy TEXT NOT NULL DEFAULT 'exact',
+    verification_status TEXT NOT NULL DEFAULT 'unverified',
+    evidence_kind TEXT NOT NULL DEFAULT 'applied',
+    exclusion_reason TEXT NOT NULL DEFAULT '',
     created_at TEXT NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_asset_snapshots_basis_date ON asset_snapshots(basis_date);
 CREATE INDEX IF NOT EXISTS idx_asset_snapshots_source ON asset_snapshots(source_type, source_id);
 
+CREATE TABLE IF NOT EXISTS asset_snapshot_runs (
+    id TEXT PRIMARY KEY,
+    basis_date TEXT NOT NULL,
+    close_status TEXT NOT NULL,
+    selection_policy TEXT NOT NULL DEFAULT 'exact',
+    idempotency_key TEXT NOT NULL DEFAULT '',
+    approved_by TEXT NOT NULL DEFAULT '',
+    approved_at TEXT NOT NULL DEFAULT '',
+    approval_reason TEXT NOT NULL DEFAULT '',
+    approval_reference TEXT NOT NULL DEFAULT '',
+    correction_of_run_id TEXT NOT NULL DEFAULT '',
+    correction_reason TEXT NOT NULL DEFAULT '',
+    applied_evidence TEXT NOT NULL DEFAULT '[]',
+    excluded_evidence TEXT NOT NULL DEFAULT '[]',
+    carried_evidence TEXT NOT NULL DEFAULT '[]',
+    request_fingerprint TEXT NOT NULL DEFAULT '',
+    created_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_idempotency ON asset_snapshot_runs(idempotency_key) WHERE idempotency_key <> '';
+CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_initial_basis ON asset_snapshot_runs(basis_date) WHERE correction_of_run_id = '';
+CREATE UNIQUE INDEX IF NOT EXISTS idx_asset_snapshot_runs_correction_parent ON asset_snapshot_runs(correction_of_run_id) WHERE correction_of_run_id <> '';
+
 CREATE TABLE IF NOT EXISTS review_decisions (
     id TEXT PRIMARY KEY,
     target_type TEXT NOT NULL,
@@ -204,7 +231,41 @@ CREATE TABLE IF NOT EXISTS reconciliation_sessions (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_reconciliation_sessions_account_basis ON reconciliation_sessions(account_id, basis_date);
 CREATE INDEX IF NOT EXISTS idx_reconciliation_sessions_status ON reconciliation_sessions(status, closed_at);
 
-INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', '11');
+CREATE TABLE IF NOT EXISTS account_valuations (
+    id TEXT PRIMARY KEY,
+    account_id TEXT NOT NULL REFERENCES accounts(id),
+    basis_date TEXT NOT NULL,
+    amount INTEGER NOT NULL,
+    currency TEXT NOT NULL DEFAULT 'KRW',
+    valuation_kind TEXT NOT NULL DEFAULT 'balance',
+    source_type TEXT NOT NULL DEFAULT 'manual',
+    source_ref TEXT NOT NULL DEFAULT '',
+    verification_status TEXT NOT NULL DEFAULT 'unverified',
+    recorded_at TEXT NOT NULL,
+    memo TEXT NOT NULL DEFAULT '',
+    idempotency_key TEXT NOT NULL DEFAULT '',
+    supersedes_id TEXT REFERENCES account_valuations(id),
+    correction_reason TEXT NOT NULL DEFAULT '',
+    as_of_at TEXT,
+    timezone TEXT,
+    cost_basis INTEGER,
+    net_contributed INTEGER,
+    reported_principal_kind TEXT,
+    reported_principal_label TEXT,
+    profit INTEGER,
+    return_rate REAL,
+    return_basis TEXT,
+    principal INTEGER,
+    interest INTEGER,
+    fee INTEGER,
+    representative_liability_definition TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_account_valuations_account_date ON account_valuations(account_id, basis_date, recorded_at);
+CREATE INDEX IF NOT EXISTS idx_account_valuations_status_date ON account_valuations(verification_status, basis_date);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_valuations_idempotency ON account_valuations(account_id, idempotency_key) WHERE idempotency_key <> '';
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_valuations_single_correction ON account_valuations(supersedes_id) WHERE supersedes_id IS NOT NULL;
+
+INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', '12');
 """
 
 ACCOUNT_ADDITIVE_COLUMNS: dict[str, str] = {

jarca_ledger_mcp/service.py

@@ -4,6 +4,7 @@ import sys
 from types import ModuleType
 
 from .application import accounts_write_services as _accounts_write_services
+from .application import account_valuation_service as _account_valuation_service
 from .application import asset_account_services as _asset_account_services
 from .application import assets_service as _assets_service
 from .application import budgets_write_services as _budgets_write_services
@@ -27,6 +28,7 @@ _current_kst_datetime = _shared._current_kst_datetime
 _PROXY_MODULES = (
     _shared,
     _accounts_write_services,
+    _account_valuation_service,
     _system_services,
     _asset_account_services,
     _assets_service,