trex-core/trex_core/application/portfolio.py

"""Portfolio snapshot read + selection (REQ-027/028/029/030/031, dcy-005).

Application-layer port for reading portfolio-hub universe + in-process
snapshot store + asset-selection service. Domain stays free of HTTP and
RabbitMQ deps (NFR-1).

The snapshot is split between:
  - in-memory `SnapshotStore`          universe + cash/position + warnings (process-local;
                                        warning is automatic/temporary, reset on restart)
  - durable `PauseStore`               portfolio_id -> paused (Postgres; manual/persistent,
                                        survives restart and daily refresh — REQ-032)
  - durable `ReconcileWarningStore`    slot_id -> reconcile-warning (Postgres; automatic,
                                        set by reconcile B/C cases, cleared by sync/verify
                                        — REQ-102, dcy-034)
"""
from __future__ import annotations

import threading
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime
from enum import Enum
from typing import Protocol

# ---------------------------------------------------------------- portfolio-hub

@dataclass(frozen=True)
class PortfolioItem:
    """One asset in the daemon's portfolio universe (REQ-027 AC-1).

    Mirrors portfolio-hub's `list_portfolios_v1` PortfolioItem with **no price
    field** — pricing is the strategy module's concern, not core's.

    REQ-116 (BAT-055): strategy_name and markets added additively.
    strategy_params already existed; now surfaced in slot_to_dict output.
    """
    portfolio_id: str               # == asset_id, dcy-004 OQ-1
    symbol: str
    cash_balance: float
    asset_quantity: float           # integer shares semantically; float for tolerance
    active_strategy_id: str | None = None
    strategy_params: dict = field(default_factory=dict)  # opaque, pass-through
    # REQ-116 additive fields (BAT-055) — safe defaults for legacy hub responses
    strategy_name: str | None = None        # portfolio-hub strategy_name; None if absent
    markets: list = field(default_factory=list)  # portfolio-hub markets list; [] if absent


class PortfolioHubReadError(Exception):
    """Base class for portfolio-hub read failures."""


class PortfolioHubUnavailableError(PortfolioHubReadError):
    """portfolio-hub unreachable / 5xx / timeout — degraded signal upstream."""


# ---------------------------------------------------------------- realized PnL (REQ-109)

@dataclass(frozen=True)
class RealizedPnlItem:
    """Single sell-trade realized PnL item from portfolio-hub WAC response.

    Maps to portfolio-hub RealizedPnlItem schema (REQ-040).
    Minimum required: symbol, realized_pnl, sell_qty.
    Additional fields preserved for completeness.
    """
    symbol: str | None
    realized_pnl: float
    sell_qty: float
    cost_basis_per_unit: float = 0.0
    fee_amount: float = 0.0
    tax_amount: float = 0.0


@dataclass(frozen=True)
class RealizedPnlResult:
    """Aggregated WAC realized PnL result for one portfolio (REQ-109).

    Returned by get_realized_pnl port method.
    """
    items: list[RealizedPnlItem]
    cost_basis_from: str | None           # ISO date string or None
    data_completeness_warning: bool          # True when portfolio-hub signals incomplete history
    total_realized_pnl: float


# ---------------------------------------------------------------- broker credential (REQ-112)

@dataclass(frozen=True)
class BrokerCredentialPayload:
    """KIS broker credential fetched from portfolio-hub (REQ-112).

    Carries app_key/app_secret/account_ref for KIS API authentication.
    credential_version is optional (portfolio-hub versioning, informational only).
    NFR-2: app_secret must never be logged in plaintext.
    """
    account_ref: str
    app_key: str
    app_secret: str
    credential_version: int | None = None


@dataclass(frozen=True)
class TradingContext:
    """Combined broker credential + trading_enabled flag from /v1/user_info (REQ-112).

    Returned by fetch_broker_credential() in a single atomic read to avoid
    double HTTP calls.
    """
    broker: BrokerCredentialPayload | None
    trading_enabled: bool


class PortfolioHubReadPort(Protocol):
    """Read-side contract for portfolio-hub universe (REQ-027) + realized PnL (REQ-109)
    + broker credential (REQ-112)."""

    def get_portfolios(self, daemon_id: str) -> list[PortfolioItem]:
        """Return all portfolios where `managed_by_daemon_id == daemon_id`."""
        ...

    def whoami(self) -> str:
        """Resolve daemon_id from the credentials/token (REQ-027 AC-4).

        Called once at startup so `daemon_id` lookup never depends on
        `TREX_DAEMON_ID` env (single source of truth = auth token).
        """
        ...

    def get_realized_pnl(
        self,
        portfolio_id: str,
        from_dt: str,
        to_dt: str,
        *,
        symbol: str | None = None,
    ) -> RealizedPnlResult:
        """GET /v1/portfolios/{portfolio_id}/pnl/realized — WAC realized PnL (REQ-109).

        Args:
            portfolio_id: target portfolio.
            from_dt: ISO date string (YYYY-MM-DD), sell-date inclusive start.
            to_dt: ISO date string (YYYY-MM-DD), sell-date inclusive end.
            symbol: optional symbol filter.

        Returns:
            RealizedPnlResult with per-sell items, total, cost_basis_from,
            data_completeness_warning.

        Raises:
            PortfolioHubUnavailableError: on network error or non-2xx response.
        """
        ...

    def fetch_broker_credential(self) -> TradingContext:
        """GET /v1/user_info — broker credential + trading_enabled (REQ-112).

        Returns a TradingContext with:
          - broker: BrokerCredentialPayload if the daemon has assigned credentials,
            None if broker is null (no credential assigned) or credential_payload
            is null (decryption failure).
          - trading_enabled: bool as reported by portfolio-hub.

        Raises:
            PortfolioHubUnavailableError: on network error, non-2xx (incl. 403),
                                          or JSON parse failure.
        """
        ...


class DegradedReason(str, Enum):
    """Machine-readable degraded reason codes (REQ-028 AC-2, dcy-005 OQ-5)."""
    PORTFOLIO_HUB_UNAVAILABLE = "portfolio_hub_unavailable"
    SNAPSHOT_FETCH_FAILED = "snapshot_fetch_failed"
    CASH_POSITION_STALE = "cash_position_stale"


# ---------------------------------------------------------------- snapshot store

@dataclass(frozen=True)
class SnapshotAsset:
    """A portfolio item augmented with overlays (warning, sequence)."""
    item: PortfolioItem
    warning: bool = False
    updated_at: datetime | None = None


class SnapshotStore:
    """In-memory snapshot — universe baseline + warning overlay.

    Two-phase: callers `swap(new_universe)` to atomically replace the universe
    after a fetch, and `set_warning(portfolio_id, on)` to toggle the automatic
    warning overlay (REQ-031). pause overlay lives in PauseStore (REQ-032).

    Thread-safe; the snapshot RPC handler can read concurrently with the
    scheduler refresh.
    """

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._assets: dict[str, SnapshotAsset] = {}
        self._degraded: DegradedReason | None = None
        self._degraded_message: str | None = None
        self._last_refresh_at: datetime | None = None

    # --- universe ---
    def swap(self, items: list[PortfolioItem]) -> None:
        """Replace the entire universe atomically (immutable swap, Decision 6)."""
        now = datetime.now(tz=UTC)
        with self._lock:
            prior_warnings = {pid for pid, a in self._assets.items() if a.warning}
            new_assets: dict[str, SnapshotAsset] = {}
            for item in items:
                # Carry forward warning if the same portfolio was warned before;
                # reconciliation will clear it on the next successful check.
                warn = item.portfolio_id in prior_warnings
                new_assets[item.portfolio_id] = SnapshotAsset(
                    item=item, warning=warn, updated_at=now,
                )
            self._assets = new_assets
            self._degraded = None
            self._degraded_message = None
            self._last_refresh_at = now

    def list_assets(self) -> list[SnapshotAsset]:
        with self._lock:
            return list(self._assets.values())

    def get(self, portfolio_id: str) -> SnapshotAsset | None:
        with self._lock:
            return self._assets.get(portfolio_id)

    # --- warning overlay (automatic, in-memory only) ---
    def set_warning(self, portfolio_id: str, on: bool) -> None:
        with self._lock:
            a = self._assets.get(portfolio_id)
            if a is None or a.warning is on:
                return
            self._assets[portfolio_id] = replace(a, warning=on)

    def warnings(self) -> set[str]:
        with self._lock:
            return {pid for pid, a in self._assets.items() if a.warning}

    # --- option D cash/position (REQ-030 AC-2/AC-3 — wired but no-op until
    #     portfolio-hub#8 ships) ---
    def update_cash_position(
        self,
        portfolio_id: str,
        cash_balance: float,
        asset_quantity: float,
    ) -> None:
        with self._lock:
            a = self._assets.get(portfolio_id)
            if a is None:
                return
            self._assets[portfolio_id] = replace(
                a, item=replace(a.item, cash_balance=cash_balance,
                                 asset_quantity=asset_quantity),
                updated_at=datetime.now(tz=UTC),
            )

    # --- degraded signal (REQ-028 AC-2) ---
    def set_degraded(self, reason: DegradedReason, message: str) -> None:
        with self._lock:
            self._degraded = reason
            self._degraded_message = _sanitize(message)

    def clear_degraded(self) -> None:
        with self._lock:
            self._degraded = None
            self._degraded_message = None

    def degraded_state(self) -> tuple[DegradedReason | None, str | None]:
        with self._lock:
            return self._degraded, self._degraded_message

    def last_refresh_at(self) -> datetime | None:
        with self._lock:
            return self._last_refresh_at


# ---------------------------------------------------------------- pause store

class PauseStore(Protocol):
    """Durable pause overlay — `portfolio_id` PK (REQ-032)."""

    def list_paused(self) -> set[str]:
        ...

    def pause(self, portfolio_id: str, *, actor: str = "operator") -> None:
        ...

    def resume(self, portfolio_id: str) -> None:
        ...


class InMemoryPauseStore:
    """Process-local pause store for tests + CI."""

    def __init__(self, initial: set[str] | None = None) -> None:
        self._lock = threading.Lock()
        self._paused: set[str] = set(initial or set())

    def list_paused(self) -> set[str]:
        with self._lock:
            return set(self._paused)

    def pause(self, portfolio_id: str, *, actor: str = "operator") -> None:
        with self._lock:
            self._paused.add(portfolio_id)

    def resume(self, portfolio_id: str) -> None:
        with self._lock:
            self._paused.discard(portfolio_id)


# ---------------------------------------------------------------- kill-switch
# Day-scoped exclusion overlay (REQ-044/046 / BAT-012). Distinct from pause:
# keyed by (portfolio_id, trading_date) so it auto-clears next trading day.
GLOBAL_KILLSWITCH = "*"  # sentinel: whole-universe exclusion for the day


class KillSwitchStore(Protocol):
    """Day-scoped kill-switch exclusion overlay (REQ-044)."""

    def list_excluded(self, trading_date) -> set[str]:
        ...

    def exclude(self, portfolio_id: str, trading_date, *, actor: str = "kill-switch") -> None:
        ...

    def clear(self, portfolio_id: str, trading_date) -> None:
        ...


class InMemoryKillSwitchStore:
    """Process-local day-scoped kill-switch store for tests + CI."""

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._excluded: set[tuple[str, object]] = set()  # (portfolio_id, trading_date)

    def list_excluded(self, trading_date) -> set[str]:
        with self._lock:
            return {pid for pid, d in self._excluded if d == trading_date}

    def exclude(self, portfolio_id: str, trading_date, *, actor: str = "kill-switch") -> None:
        with self._lock:
            self._excluded.add((portfolio_id, trading_date))

    def clear(self, portfolio_id: str, trading_date) -> None:
        with self._lock:
            self._excluded.discard((portfolio_id, trading_date))


# ---------------------------------------------------------------- reconcile-warning store (REQ-102)
# BAT-050 / dcy-034: durable reconcile-warning channel — distinct from pause (manual).
# Keyed by slot_id (TEXT UUID string). case_code: 'B' (slot↔broker qty mismatch)
# or 'C' (ledger↔broker mismatch). Survives restart (PostgreSQL-backed in production).


class ReconcileWarningStore(Protocol):
    """Durable reconcile-warning overlay — slot_id PK (REQ-102, dcy-034)."""

    def set_warned(
        self,
        slot_id: str,
        *,
        portfolio_id: str,
        case_code: str,
        actor: str = "reconcile",
        reason: str = "",
    ) -> None:
        ...

    def clear_warned(self, slot_id: str) -> None:
        ...

    def is_warned(self, slot_id: str) -> bool:
        ...

    def list_warned(self) -> set[str]:
        ...

    def get_warning_info(self, slot_id: str) -> dict | None:
        """Return {"portfolio_id", "case_code", "actor", "reason"} or None.

        Used by verify to determine whether the warning is case_code='C'
        (verify's responsibility) vs 'B' (sync's responsibility, REQ-106 OQ-C).
        Returns None when the slot has no active warning.
        """
        ...

    def list_c_case_warned(self) -> set[str]:
        """Return set of slot_id strings that have an active case_code='C' warning.

        AC-0023: used by strategy slots RPC to exclude C-case mismatched holding slots.
        """
        ...


class InMemoryReconcileWarningStore:
    """Process-local reconcile-warning store for tests + CI (REQ-102)."""

    def __init__(self) -> None:
        self._lock = threading.Lock()
        # slot_id -> {"portfolio_id", "case_code", "actor", "reason"}
        self._warned: dict[str, dict] = {}

    def set_warned(
        self,
        slot_id: str,
        *,
        portfolio_id: str,
        case_code: str,
        actor: str = "reconcile",
        reason: str = "",
    ) -> None:
        with self._lock:
            self._warned[slot_id] = {
                "portfolio_id": portfolio_id,
                "case_code": case_code,
                "actor": actor,
                "reason": reason,
            }

    def clear_warned(self, slot_id: str) -> None:
        with self._lock:
            self._warned.pop(slot_id, None)

    def is_warned(self, slot_id: str) -> bool:
        with self._lock:
            return slot_id in self._warned

    def list_warned(self) -> set[str]:
        with self._lock:
            return set(self._warned.keys())

    def get_warning_info(self, slot_id: str) -> dict | None:
        with self._lock:
            info = self._warned.get(slot_id)
            return dict(info) if info is not None else None

    def list_c_case_warned(self) -> set[str]:
        with self._lock:
            return {sid for sid, info in self._warned.items() if info.get("case_code") == "C"}


class ReconcileNotificationStore(Protocol):
    """Durable mismatch notification lifecycle store (req-0007, ac-0024).

    Tracks the last successfully published fingerprint for each B/C-case identity
    to suppress duplicate alarms across scheduler ticks and process restarts.

    Identity keys:
      B-case: slot_id (UUID string)
      C-case: `"{instance_key}\\x00C\\x00{symbol}"` (null-separated to avoid collisions)

    lifecycle_state values:
      "notified"         — detected or changed alarm was published for this fingerprint
      "pending_resolved" — warning was cleared but resolved publish failed; retry pending
    """

    def get_state(self, identity_key: str) -> dict | None:
        """Return state dict or None.

        State dict keys: identity_key, case_code, instance_key, symbol,
        quantity_a, quantity_b, lifecycle_state.
        """
        ...

    def set_state(
        self,
        identity_key: str,
        *,
        case_code: str,
        instance_key: str,
        symbol: str,
        quantity_a: int,
        quantity_b: int,
        lifecycle_state: str,
    ) -> None:
        """Upsert notification state (call after successful publish)."""
        ...

    def clear_state(self, identity_key: str) -> None:
        """Remove state (call after successful resolved publish)."""
        ...

    def list_states_by_lifecycle(self, lifecycle_state: str) -> list[dict]:
        """Return all state dicts with the given lifecycle_state."""
        ...


class InMemoryReconcileNotificationStore:
    """Process-local notification lifecycle store for tests + CI (req-0007)."""

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._states: dict[str, dict] = {}

    def get_state(self, identity_key: str) -> dict | None:
        with self._lock:
            s = self._states.get(identity_key)
            return dict(s) if s is not None else None

    def set_state(
        self,
        identity_key: str,
        *,
        case_code: str,
        instance_key: str,
        symbol: str,
        quantity_a: int,
        quantity_b: int,
        lifecycle_state: str,
    ) -> None:
        with self._lock:
            self._states[identity_key] = {
                "identity_key": identity_key,
                "case_code": case_code,
                "instance_key": instance_key,
                "symbol": symbol,
                "quantity_a": quantity_a,
                "quantity_b": quantity_b,
                "lifecycle_state": lifecycle_state,
            }

    def clear_state(self, identity_key: str) -> None:
        with self._lock:
            self._states.pop(identity_key, None)

    def list_states_by_lifecycle(self, lifecycle_state: str) -> list[dict]:
        with self._lock:
            return [
                dict(s) for s in self._states.values()
                if s["lifecycle_state"] == lifecycle_state
            ]


def slot_to_dict(
    s,
    *,
    snapshot_store: SnapshotStore | None = None,
    watchdog_store=None,
    pause_store: PauseStore | None = None,
    warn_store: ReconcileWarningStore | None = None,
    watchdog_timeout_sec: int = 120,
) -> dict:
    """Merged slot row for trex.slots.req (REQ-073/074).

    Carries slot/core state + hub asset data + watchdog + overlay flags.
    Field-level authority: slot/core = slot_id/status/qty/avg_price/entry_price/
    forced_close_at; hub = asset_quantity/cash_balance; watchdog = watchdog{};
    overlay = paused/warned/reconcile_warned. strategy fields excluded (REQ-074 AC-5).
    """
    d = {
        "slot_id": str(s.slot_id),
        "status": s.status.value,
        "symbol": s.symbol,
        "qty": float(s.qty) if s.qty is not None else None,
        "avg_price": float(s.avg_price) if s.avg_price is not None else None,
        "entry_price": float(s.limit_price) if s.limit_price is not None else None,
        "portfolio_id": s.portfolio_id,
        "forced_close_at": s.forced_close_at.isoformat() if s.forced_close_at else None,
        "universe_detached": getattr(s, "retired_at", None) is not None,
        # dcy-028/REQ-081 (BAT-042): per-occupancy guard counter — the strategy
        # daemon echoes this as expected_occupancy_seq on strategy_state writes.
        "occupancy_seq": getattr(s, "occupancy_seq", 0),
    }

    # hub authority: asset_quantity (hub primary) + cash_balance
    # REQ-116: strategy_name / strategy_params / markets also from PortfolioItem
    asset_qty: float | None = None
    cash_balance: float | None = None
    strategy_name_val: str | None = None
    strategy_params_val: dict = {}
    markets_val: list = []
    if snapshot_store is not None and s.portfolio_id:
        snap = snapshot_store.get(s.portfolio_id)
        if snap is not None:
            asset_qty = float(snap.item.asset_quantity)
            cash_balance = float(snap.item.cash_balance)
            # REQ-116 (BAT-055): strategy fields from PortfolioItem (hub authority)
            strategy_name_val = snap.item.strategy_name
            strategy_params_val = dict(snap.item.strategy_params)
            markets_val = list(snap.item.markets)

    # qty (slot mirror) vs asset_quantity (hub): divergence → warned=True
    slot_qty = float(s.qty) if s.qty is not None else None
    warned = bool(slot_qty != asset_qty) if (slot_qty is not None and asset_qty is not None) else False

    d["asset_quantity"] = asset_qty
    d["cash_balance"] = cash_balance
    d["cash_estimated"] = False  # handler overlays ledger_outbox estimate if available
    d["warned"] = warned
    # REQ-116 (BAT-055): strategy fields — additive, safe default when hub absent
    d["strategy_name"] = strategy_name_val
    d["strategy_params"] = strategy_params_val
    d["markets"] = markets_val

    # watchdog nested object (WatchdogStore)
    if watchdog_store is not None:
        sid = str(s.slot_id)
        last = watchdog_store.last_seen(sid)
        d["watchdog"] = {
            "expired": watchdog_store.is_expired(sid, watchdog_timeout_sec),
            "last_seen": last.isoformat() if last else None,
        }
    else:
        d["watchdog"] = None

    # paused overlay (PauseStore) — orthogonal to status
    paused = False
    if pause_store is not None and s.portfolio_id:
        paused = s.portfolio_id in pause_store.list_paused()
    d["paused"] = paused

    # BAT-050 / REQ-104: reconcile_warned overlay (ReconcileWarningStore) — additive field.
    # Bulk list_warned() called once per RPC (caller pre-fetches; see make_slots_rpc_handler).
    # warn_store=None → reconcile_warned=False (backward compatible, NFR-4).
    reconcile_warned = False
    if warn_store is not None:
        reconcile_warned = str(s.slot_id) in warn_store.list_warned()
    d["reconcile_warned"] = reconcile_warned

    return d


def _sanitize(message: str) -> str:
    """Strip credentials/URLs/tokens from degraded messages."""
    if not message:
        return ""
    out = message
    for needle in ("authorization:", "Bearer ", "token=", "appsecret="):
        idx = out.lower().find(needle.lower())
        if idx >= 0:
            out = out[:idx] + "<redacted>"
            break
    return out[:200]