"""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

BLOCKING_RECONCILE_CASES = frozenset({"B", "C"})

# ---------------------------------------------------------------- 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 keyed by (slot_id, case_code)."""

    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, *, case_code: str | None = None) -> 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 warning info dict or None.

        Returned dict includes:
          {"portfolio_id", "case_code", "case_codes", "actor", "reason"}
        where case_code is a backward-compatible preferred case and case_codes is
        the full active case set for the slot.

        Used by verify to determine whether C-case is active (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 -> case_code -> {"portfolio_id", "actor", "reason"}
        self._warned: dict[str, 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:
            per_case = self._warned.setdefault(slot_id, {})
            per_case[case_code] = {
                "portfolio_id": portfolio_id,
                "actor": actor,
                "reason": reason,
            }

    def clear_warned(self, slot_id: str, *, case_code: str | None = None) -> None:
        with self._lock:
            if case_code is None:
                self._warned.pop(slot_id, None)
                return
            per_case = self._warned.get(slot_id)
            if not per_case:
                return
            per_case.pop(case_code, None)
            if not per_case:
                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:
            per_case = self._warned.get(slot_id)
            if not per_case:
                return None
            case_codes = sorted(per_case.keys())
            preferred_case = "C" if "C" in per_case else case_codes[0]
            preferred = per_case[preferred_case]
            return {
                "portfolio_id": preferred.get("portfolio_id", ""),
                "case_code": preferred_case,
                "case_codes": case_codes,
                "actor": preferred.get("actor", ""),
                "reason": preferred.get("reason", ""),
            }

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


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
            ]


class UnmanagedPositionStore(Protocol):
    """Durable unmanaged-position lifecycle store keyed by (instance_key, symbol)."""

    def observe(
        self,
        *,
        instance_key: str,
        symbol: str,
        quantity: int,
        observed_at: datetime | None = None,
        actor: str = "reconcile",
    ) -> dict:
        """Return {"transition", "previous_quantity", "state"} for one observation."""
        ...

    def resolve_absent(
        self,
        *,
        instance_key: str,
        observed_symbols: set[str],
        observed_at: datetime | None = None,
        actor: str = "reconcile",
    ) -> list[dict]:
        """Mark active positions absent from a successful broker read as resolved."""
        ...

    def get_state(self, *, instance_key: str, symbol: str) -> dict | None:
        ...

    def list_states(
        self,
        *,
        instance_key: str,
        lifecycle_state: str = "active",
        symbol: str | None = None,
    ) -> list[dict]:
        ...

    def record_operator_action(
        self,
        *,
        instance_key: str,
        symbol: str,
        action: str,
        evidence_ref: str,
        actor: str = "operator",
        note: str = "",
    ) -> dict | None:
        """Persist an explicit operator disposition and append an audit event."""
        ...

    def list_audit(self, *, instance_key: str, symbol: str) -> list[dict]:
        ...


class InMemoryUnmanagedPositionStore:
    """Process-local unmanaged-position lifecycle store for tests + CI."""

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

    def observe(
        self,
        *,
        instance_key: str,
        symbol: str,
        quantity: int,
        observed_at: datetime | None = None,
        actor: str = "reconcile",
    ) -> dict:
        now = observed_at or datetime.now(tz=UTC)
        key = (instance_key, symbol)
        with self._lock:
            existing = self._states.get(key)
            previous_quantity = existing.get("quantity") if existing is not None else None
            preserved = {} if existing is None else {
                "created_at": existing.get("created_at", now),
            }
            if existing is None or existing.get("lifecycle_state") == "resolved":
                transition = "detected"
                state = {
                    "instance_key": instance_key,
                    "symbol": symbol,
                    "quantity": quantity,
                    "lifecycle_state": "active",
                    "first_seen_at": (
                        existing.get("first_seen_at", now) if existing is not None else now
                    ),
                    "last_seen_at": now,
                    "quantity_changed_at": now,
                    "resolved_at": None,
                    "operator_action": None,
                    "evidence_ref": None,
                    "operator_note": "",
                    "operator_actor": None,
                    "operator_updated_at": None,
                    "recorded_at": now,
                    **preserved,
                    "updated_at": now,
                }
                self._states[key] = state
            elif int(existing["quantity"]) != int(quantity):
                transition = "quantity_changed"
                existing["quantity"] = quantity
                existing["last_seen_at"] = now
                existing["quantity_changed_at"] = now
                existing["resolved_at"] = None
                existing["lifecycle_state"] = "active"
                existing["updated_at"] = now
                state = existing
            else:
                transition = "unchanged"
                existing["last_seen_at"] = now
                existing["updated_at"] = now
                state = existing
            if transition != "unchanged":
                self._audit.append(
                    {
                        "instance_key": instance_key,
                        "symbol": symbol,
                        "event_type": transition,
                        "action": None,
                        "quantity": quantity,
                        "lifecycle_state": state["lifecycle_state"],
                        "actor": actor,
                        "evidence_ref": state.get("evidence_ref"),
                        "note": (
                            f"previous_quantity={previous_quantity}"
                            if transition == "quantity_changed" and previous_quantity is not None
                            else ""
                        ),
                        "recorded_at": now,
                    }
                )
            return {
                "transition": transition,
                "previous_quantity": previous_quantity,
                "state": dict(state),
            }

    def resolve_absent(
        self,
        *,
        instance_key: str,
        observed_symbols: set[str],
        observed_at: datetime | None = None,
        actor: str = "reconcile",
    ) -> list[dict]:
        now = observed_at or datetime.now(tz=UTC)
        with self._lock:
            resolved: list[dict] = []
            for key, state in sorted(self._states.items()):
                if key[0] != instance_key:
                    continue
                if state.get("lifecycle_state") != "active":
                    continue
                if state["symbol"] in observed_symbols:
                    continue
                state["lifecycle_state"] = "resolved"
                state["resolved_at"] = now
                state["updated_at"] = now
                resolved.append(dict(state))
                self._audit.append(
                    {
                        "instance_key": state["instance_key"],
                        "symbol": state["symbol"],
                        "event_type": "resolved",
                        "action": None,
                        "quantity": state["quantity"],
                        "lifecycle_state": "resolved",
                        "actor": actor,
                        "evidence_ref": state.get("evidence_ref"),
                        "note": "",
                        "recorded_at": now,
                    }
                )
            return resolved

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

    def list_states(
        self,
        *,
        instance_key: str,
        lifecycle_state: str = "active",
        symbol: str | None = None,
    ) -> list[dict]:
        with self._lock:
            rows = []
            for state in self._states.values():
                if state["instance_key"] != instance_key:
                    continue
                if lifecycle_state != "all" and state["lifecycle_state"] != lifecycle_state:
                    continue
                if symbol is not None and state["symbol"] != symbol:
                    continue
                rows.append(dict(state))
            return sorted(rows, key=lambda item: item["symbol"])

    def record_operator_action(
        self,
        *,
        instance_key: str,
        symbol: str,
        action: str,
        evidence_ref: str,
        actor: str = "operator",
        note: str = "",
    ) -> dict | None:
        now = datetime.now(tz=UTC)
        with self._lock:
            state = self._states.get((instance_key, symbol))
            if state is None:
                return None
            state["operator_action"] = action
            state["evidence_ref"] = evidence_ref
            state["operator_note"] = note
            state["operator_actor"] = actor
            state["operator_updated_at"] = now
            state["updated_at"] = now
            self._audit.append(
                {
                    "instance_key": instance_key,
                    "symbol": symbol,
                    "event_type": "operator_action",
                    "action": action,
                    "quantity": state["quantity"],
                    "lifecycle_state": state["lifecycle_state"],
                    "actor": actor,
                    "evidence_ref": evidence_ref,
                    "note": note,
                    "recorded_at": now,
                }
            )
            return dict(state)

    def list_audit(self, *, instance_key: str, symbol: str) -> list[dict]:
        with self._lock:
            return [
                dict(row)
                for row in self._audit
                if row["instance_key"] == instance_key and row["symbol"] == symbol
            ]


def slot_to_dict(
    s,
    *,
    snapshot_store: SnapshotStore | None = None,
    watchdog_store=None,
    pause_store: PauseStore | None = None,
    warn_store: ReconcileWarningStore | None = None,
    warning_cases_by_slot: dict[str, set[str]] | 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
        # Slot occupancy remains domain state; strategy-state writes do not use it.
        "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).
    warning_cases: set[str] = set()
    if warning_cases_by_slot is not None:
        warning_cases = set(warning_cases_by_slot.get(str(s.slot_id), set()))
    elif warn_store is not None:
        info = warn_store.get_warning_info(str(s.slot_id))
        if info is not None:
            raw_cases = info.get("case_codes")
            if isinstance(raw_cases, list):
                warning_cases = {str(c) for c in raw_cases if c}
            else:
                case_code = str(info.get("case_code", ""))
                if case_code:
                    warning_cases = {case_code}
    reconcile_warned = bool(warning_cases)
    d["reconcile_warned"] = reconcile_warned
    d["reconcile_warning_cases"] = sorted(warning_cases)
    known_blocking = bool(warning_cases & BLOCKING_RECONCILE_CASES)
    unknown_cases = bool(warning_cases - BLOCKING_RECONCILE_CASES)
    d["trade_eligible"] = not (known_blocking or unknown_cases)

    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]