feat: add portfolio snapshot read layer

trex_core/application/broker_port.py

@@ -29,6 +29,18 @@ class OrderAck:
     raw: dict[str, Any] = field(default_factory=dict)
 
 
+@dataclass(frozen=True)
+class BalanceItem:
+    """One symbol in a broker account balance (REQ-031, BAT-008).
+
+    KIS `TTTC8434R`/`VTTC8434R` returns per-symbol `pdno` + `hldg_qty`. The
+    paper broker returns a deterministic in-memory ledger keyed by symbol.
+    """
+    symbol: str         # KIS `pdno`
+    hldg_qty: int       # held quantity (integer shares; D-2 zero-qty rows are
+                        # treated as not-held — design Decision 7)
+
+
 @dataclass(frozen=True)
 class FillStatus:
     state: str            # accepted | partially_filled | filled | rejected | cancelled | unknown
@@ -69,6 +81,15 @@ class BrokerPort(Protocol):
         """Best-effort cancel. Returns True if the broker accepted the cancel."""
         ...
 
+    def get_balance(self) -> list[BalanceItem]:
+        """Per-symbol balance for the broker's single account (REQ-031).
+
+        Returns symbol+hldg_qty rows. Adapters MUST drop zero-qty rows so
+        D-2 leftover entries (KIS keeps `hldg_qty=0` for two days after a
+        full-sell) are reported as not-held (Design Decision 7).
+        """
+        ...
+
 
 # --- shared fee model (REQ-018, orbit calculate_fee pattern) -----------------
 # Conservative KR equities approximation (bps). Brokers can override, but we

trex_core/application/messaging_handlers.py

@@ -14,6 +14,12 @@ from uuid import UUID
 
 from trex_core.application.intents import BuyIntent, IntentService, SellIntent
 from trex_core.application.messaging import RpcRequest, RpcResponse
+from trex_core.application.portfolio import (
+    PauseStore,
+    SnapshotStore,
+    View,
+    build_snapshot_envelope,
+)
 from trex_core.domain.slot import SlotRepository, SlotService
 
 _log = logging.getLogger(__name__)
@@ -89,32 +95,68 @@ def make_intent_rpc_handler(intent_service: IntentService):
 
 # ---- snapshot RPC handler ---------------------------------------------------
 
-def make_snapshot_rpc_handler(slot_repo: SlotRepository, slot_service: SlotService):
-    """Build the RPC handler for `trex.snapshot.req`.
+def make_snapshot_rpc_handler(
+    slot_repo: SlotRepository,
+    slot_service: SlotService,
+    *,
+    snapshot_store: Optional[SnapshotStore] = None,
+    pause_store: Optional[PauseStore] = None,
+    default_total_slots: int = 10,
+):
+    """Build the RPC handler for `trex.snapshot.req` (REQ-028).
 
-    Payload shape (stub for BAT-007 — dcy-005 logical contract is not yet
-    REQ-normalized; this returns a transport-shape evidence equivalent of
-    `GET /v1/slots` + `GET /v1/capacity`):
+    When `snapshot_store` + `pause_store` are provided (production wiring),
+    returns the BAT-008 envelope:
         {
-          "strategy_id": "<filter or null>",
-          "view":        "open" | "all"   (default "all"),
-          "trading_date": "YYYY-MM-DD"    (optional, default today UTC)
+          "assets":          list of {symbol, asset_id, cash_balance,
+                                       asset_quantity, active_strategy_id,
+                                       strategy_params},
+          "view":            "all" | "buyable" | "held",
+          "available_slots": int,
+          "degraded":        bool,
+          "reason":          DegradedReason value or null,
+          "message":         sanitized text or null
         }
+
+    Without those, falls back to the BAT-007 slot+capacity stub shape so
+    older callers and existing tests don't break.
     """
 
     def handler(req: RpcRequest) -> RpcResponse:
         body = req.payload or {}
-        view = str(body.get("view") or "all")
-        strategy_filter = _opt_str(body.get("strategy_id"))
         day = _parse_date(body.get("trading_date")) if body.get("trading_date") else _today()
+
+        # --- BAT-008 envelope path (snapshot store wired) ---
+        if snapshot_store is not None and pause_store is not None:
+            requested_view = str(body.get("view") or "all").lower()
+            try:
+                view = View(requested_view)
+            except ValueError:
+                view = View.ALL
+            strategy_key = _opt_str(body.get("strategy_key"))
+            cap = slot_service.compute_slot_capacity(day, default_total_slots)
+            envelope = build_snapshot_envelope(
+                store=snapshot_store,
+                pause_store=pause_store,
+                slot_repo=slot_repo,
+                available_slots=cap.idle_count,
+                view=view,
+                strategy_key=strategy_key,
+                trading_date=day,
+            )
+            return RpcResponse(payload=envelope.to_dict())
+
+        # --- BAT-007 legacy stub-shape path ---
+        view_raw = str(body.get("view") or "all")
+        strategy_filter = _opt_str(body.get("strategy_id"))
         slots = slot_repo.list_slots(day)
-        if view == "open":
+        if view_raw == "open":
             slots = [s for s in slots if s.status.value in ("pending_buy", "holding", "pending_sell")]
         if strategy_filter is not None:
             slots = [s for s in slots if s.strategy_id == strategy_filter]
         cap = slot_service.compute_slot_capacity(day, max(1, len(slot_repo.list_slots(day))))
         return RpcResponse(payload={
-            "view": view,
+            "view": view_raw,
             "strategy_id": strategy_filter,
             "trading_date": day.isoformat(),
             "slots": [_slot_to_dict(s) for s in slots],
@@ -130,6 +172,48 @@ def make_snapshot_rpc_handler(slot_repo: SlotRepository, slot_service: SlotServi
     return handler
 
 
+# ---- pause/resume RPC handler (REQ-032 AC-4) --------------------------------
+
+def make_pause_rpc_handler(pause_store: PauseStore):
+    """RPC handler for the `trex.pause.req` control queue.
+
+    Payload: {"action": "pause" | "resume" | "list", "portfolio_id": "..."}
+    Response: {"status": "ok"|"error", "paused": [list-of-portfolio_id], "reason"?: str}
+    """
+
+    def handler(req: RpcRequest) -> RpcResponse:
+        body = req.payload or {}
+        action = str(body.get("action") or "").lower()
+        pid = _opt_str(body.get("portfolio_id"))
+        actor = str(body.get("actor") or "operator")
+        try:
+            if action == "pause":
+                if not pid:
+                    return _err("portfolio_id required")
+                pause_store.pause(pid, actor=actor)
+            elif action == "resume":
+                if not pid:
+                    return _err("portfolio_id required")
+                pause_store.resume(pid)
+            elif action == "list":
+                pass
+            else:
+                return _err(f"unknown action: {action!r}")
+        except Exception as exc:  # noqa: BLE001
+            return _err(f"pause store error: {exc.__class__.__name__}")
+        return RpcResponse(payload={
+            "status": "ok",
+            "paused": sorted(pause_store.list_paused()),
+            "action": action,
+        })
+
+    return handler
+
+
+def _err(reason: str) -> RpcResponse:
+    return RpcResponse(payload={"status": "error", "reason": reason})
+
+
 # ---- event payload builder --------------------------------------------------
 
 def slot_transition_event_payload(slot, *, event_type: str) -> dict:

trex_core/application/portfolio.py

@@ -0,0 +1,361 @@
+"""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)
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional, 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.
+    """
+    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: Optional[str] = None
+    strategy_params: dict = field(default_factory=dict)  # opaque, pass-through
+
+
+class PortfolioHubReadError(Exception):
+    """Base class for portfolio-hub read failures."""
+
+
+class PortfolioHubUnavailableError(PortfolioHubReadError):
+    """portfolio-hub unreachable / 5xx / timeout — degraded signal upstream."""
+
+
+class PortfolioHubReadPort(Protocol):
+    """Read-side contract for portfolio-hub universe (REQ-027)."""
+
+    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).
+        """
+        ...
+
+
+# ---------------------------------------------------------------- selection enums
+
+class View(str, Enum):
+    """Snapshot view modes (REQ-029, dcy-005 OQ-11/OQ-12)."""
+    ALL = "all"             # universe ∪ holding slots
+    BUYABLE = "buyable"     # universe − occupied slots
+    HELD = "held"           # holding slots only
+
+
+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: Optional[datetime] = 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: Optional[DegradedReason] = None
+        self._degraded_message: Optional[str] = None
+        self._last_refresh_at: Optional[datetime] = None
+
+    # --- universe ---
+    def swap(self, items: list[PortfolioItem]) -> None:
+        """Replace the entire universe atomically (immutable swap, Decision 6)."""
+        now = datetime.now(tz=timezone.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) -> Optional[SnapshotAsset]:
+        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=timezone.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[Optional[DegradedReason], Optional[str]]:
+        with self._lock:
+            return self._degraded, self._degraded_message
+
+    def last_refresh_at(self) -> Optional[datetime]:
+        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: Optional[set[str]] = 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)
+
+
+# ---------------------------------------------------------------- selection
+
+@dataclass(frozen=True)
+class SnapshotEnvelope:
+    """REQ-028 response envelope (transport-agnostic)."""
+    assets: list[dict]
+    view: str
+    available_slots: int
+    degraded: bool
+    reason: Optional[str]
+    message: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "assets": list(self.assets),
+            "view": self.view,
+            "available_slots": self.available_slots,
+            "degraded": self.degraded,
+            "reason": self.reason,
+            "message": self.message,
+        }
+
+
+def _asset_to_dict(item: PortfolioItem) -> dict:
+    """REQ-027 AC-1 / REQ-028 AC-3 — strict no-price field shape."""
+    return {
+        "symbol": item.symbol,
+        "asset_id": item.portfolio_id,
+        "cash_balance": item.cash_balance,
+        "asset_quantity": item.asset_quantity,
+        "active_strategy_id": item.active_strategy_id,
+        "strategy_params": dict(item.strategy_params or {}),
+    }
+
+
+def _sanitize(message: str) -> str:
+    """Strip credentials/URLs/tokens — REQ-028 AC-2 sanitization."""
+    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
+    # Truncate to keep response payload bounded.
+    return out[:200]
+
+
+def build_snapshot_envelope(
+    *,
+    store: SnapshotStore,
+    pause_store: PauseStore,
+    slot_repo,
+    available_slots: int,
+    view: View = View.ALL,
+    strategy_key: Optional[str] = None,
+    trading_date=None,
+) -> SnapshotEnvelope:
+    """Compose base(view) − mask(pending·warning·pause) − strategy_key (REQ-029).
+
+    `slot_repo` is the SlotRepository used to read holding/pending state.
+    `trading_date` defaults to UTC today (matches the daemon's preallocate).
+    """
+    # Read core authoritative slot state once.
+    day = trading_date or datetime.now(tz=timezone.utc).date()
+    slots = slot_repo.list_slots(day)
+    holding_pids: set[str] = set()
+    pending_pids: set[str] = set()
+    holding_qty: dict[str, float] = {}
+    for s in slots:
+        if s.portfolio_id is None:
+            continue
+        if s.status.value == "holding":
+            holding_pids.add(s.portfolio_id)
+            holding_qty[s.portfolio_id] = float(s.qty or 0.0)
+        elif s.status.value in ("pending_buy", "pending_sell"):
+            pending_pids.add(s.portfolio_id)
+
+    assets = store.list_assets()
+    paused = pause_store.list_paused()
+    warned = {a.item.portfolio_id for a in assets if a.warning}
+
+    # Build the base set (view).
+    by_pid = {a.item.portfolio_id: a for a in assets}
+    base_pids: list[str]
+    if view is View.HELD:
+        base_pids = sorted(holding_pids)
+    elif view is View.BUYABLE:
+        if available_slots <= 0:
+            base_pids = []
+        else:
+            # universe − occupied slots (pending OR holding occupy)
+            occupied = holding_pids | pending_pids
+            base_pids = [a.item.portfolio_id for a in assets
+                         if a.item.portfolio_id not in occupied]
+    else:  # ALL
+        base_pids = list({a.item.portfolio_id for a in assets} | holding_pids)
+        base_pids.sort()
+
+    # Apply masks: pending OR warning OR pause.
+    masked = pending_pids | warned | paused
+
+    # Filter and shape.
+    out: list[dict] = []
+    for pid in base_pids:
+        if pid in masked:
+            continue
+        if pid in by_pid:
+            item = by_pid[pid].item
+        elif pid in holding_pids:
+            # holding slot for an asset NOT in the current universe (e.g. fetch
+            # gap) — synthesize a minimal item using slot data so the response
+            # still carries authoritative position info (REQ-029 slot overlay
+            # priority over portfolio-hub presence).
+            slot = next((s for s in slots if s.portfolio_id == pid), None)
+            item = PortfolioItem(
+                portfolio_id=pid,
+                symbol=(slot.symbol if slot else "") or "",
+                cash_balance=0.0,
+                asset_quantity=float((slot.qty if slot else 0.0) or 0.0),
+                active_strategy_id=(slot.strategy_id if slot else None),
+                strategy_params={},
+            )
+        else:
+            continue
+        if strategy_key is not None and item.active_strategy_id != strategy_key:
+            continue
+        d = _asset_to_dict(item)
+        # holding slot quantity wins for held assets (slot-overlay priority).
+        if pid in holding_qty:
+            d["asset_quantity"] = holding_qty[pid]
+        out.append(d)
+
+    reason_code, message = store.degraded_state()
+    return SnapshotEnvelope(
+        assets=out,
+        view=view.value,
+        available_slots=max(0, int(available_slots)),
+        degraded=reason_code is not None,
+        reason=reason_code.value if reason_code is not None else None,
+        message=message,
+    )

trex_core/application/reconciliation.py

@@ -0,0 +1,59 @@
+"""Position reconciliation between portfolio-hub and broker (REQ-031).
+
+The broker account is single (invariant B) so portfolio-hub quantities are
+aggregated to `symbol` before being compared with `BrokerPort.get_balance()`.
+Mismatches flip the asset's `warning` overlay; a subsequent successful match
+clears it automatically (in-memory only — pause is the durable channel for
+manual holds).
+"""
+from __future__ import annotations
+
+import logging
+
+from trex_core.application.broker_port import BrokerPort
+from trex_core.application.portfolio import SnapshotStore
+
+_log = logging.getLogger(__name__)
+
+
+def reconcile_positions(*, store: SnapshotStore, broker: BrokerPort) -> dict[str, str]:
+    """Run one reconciliation pass.
+
+    Returns a `{portfolio_id: 'warning' | 'cleared' | 'ok'}` map for telemetry.
+    The map is also reflected onto `store` via `set_warning(...)`.
+    """
+    broker_qty: dict[str, int] = {
+        item.symbol: int(item.hldg_qty) for item in broker.get_balance()
+    }
+
+    # Group portfolio-hub quantities by symbol so we can compare to broker's
+    # per-symbol aggregate.
+    by_symbol: dict[str, list[tuple[str, float]]] = {}
+    assets = store.list_assets()
+    for a in assets:
+        sym = a.item.symbol
+        by_symbol.setdefault(sym, []).append((a.item.portfolio_id, a.item.asset_quantity))
+
+    decisions: dict[str, str] = {}
+    for symbol, entries in by_symbol.items():
+        hub_total = int(sum(qty for _, qty in entries))
+        broker_total = broker_qty.get(symbol, 0)
+        match = hub_total == broker_total
+        for pid, _ in entries:
+            asset = store.get(pid)
+            was_warned = bool(asset and asset.warning)
+            if not match:
+                if not was_warned:
+                    _log.warning(
+                        "position warning raised: portfolio_id=%s symbol=%s "
+                        "hub=%d broker=%d", pid, symbol, hub_total, broker_total,
+                    )
+                store.set_warning(pid, True)
+                decisions[pid] = "warning"
+            else:
+                if was_warned:
+                    store.set_warning(pid, False)
+                    decisions[pid] = "cleared"
+                else:
+                    decisions[pid] = "ok"
+    return decisions

trex_core/application/snapshot_scheduler.py

@@ -0,0 +1,103 @@
+"""Daily snapshot refresh scheduler (REQ-030, dcy-005 FR-6).
+
+Wakes at the configured KST time, fetches universe from PortfolioHubReadPort,
+swaps the SnapshotStore, then runs reconciliation. Option D `*_after` writes
+(REQ-030 AC-2/AC-3) are wired through `SnapshotStore.update_cash_position`
+but disabled at the ledger layer until portfolio-hub#8 ships.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime, time, timedelta, timezone
+from typing import Callable, Optional
+
+from trex_core.application.broker_port import BrokerPort
+from trex_core.application.portfolio import (
+    DegradedReason,
+    PortfolioHubReadPort,
+    PortfolioHubUnavailableError,
+    SnapshotStore,
+)
+from trex_core.application.reconciliation import reconcile_positions
+
+_log = logging.getLogger(__name__)
+
+_KST = timezone(timedelta(hours=9))
+
+
+class SnapshotScheduler:
+    """Background-thread-friendly scheduler. Use `run_once()` for tests."""
+
+    def __init__(
+        self,
+        *,
+        read_port: PortfolioHubReadPort,
+        store: SnapshotStore,
+        broker: BrokerPort,
+        schedule_kst: time = time(hour=7, minute=30),
+        clock: Optional[Callable[[], datetime]] = None,
+    ) -> None:
+        self._read = read_port
+        self._store = store
+        self._broker = broker
+        self._schedule_kst = schedule_kst
+        self._clock = clock or (lambda: datetime.now(tz=timezone.utc))
+        self._daemon_id: Optional[str] = None
+        self._last_fired_date: Optional[datetime] = None
+
+    # ---- callable from a daemon thread loop --------------------------------
+    def run_forever(self, stop: threading.Event, *, tick_sec: float = 60.0) -> None:
+        # Boot fetch: do an immediate refresh so the first snapshot is alive
+        # before the scheduled time, then enter the cadence.
+        self.run_once()
+        while not stop.wait(tick_sec):
+            try:
+                self._maybe_tick()
+            except Exception:  # noqa: BLE001 - loop must survive transient errors
+                _log.exception("snapshot scheduler tick failed")
+
+    def _maybe_tick(self) -> None:
+        now_kst = self._clock().astimezone(_KST)
+        target = datetime.combine(now_kst.date(), self._schedule_kst, tzinfo=_KST)
+        if now_kst < target:
+            return
+        last = self._last_fired_date
+        if last is not None and last.date() == now_kst.date():
+            return  # already fired today
+        self.run_once()
+
+    # ---- the actual refresh -----------------------------------------------
+    def run_once(self) -> bool:
+        """Fetch + swap + reconcile. Returns True on success, False if degraded."""
+        if self._daemon_id is None:
+            try:
+                self._daemon_id = self._read.whoami()
+            except PortfolioHubUnavailableError as exc:
+                self._store.set_degraded(
+                    DegradedReason.PORTFOLIO_HUB_UNAVAILABLE, str(exc)
+                )
+                _log.warning("whoami failed: %s", exc)
+                return False
+        try:
+            items = self._read.get_portfolios(self._daemon_id)
+        except PortfolioHubUnavailableError as exc:
+            self._store.set_degraded(
+                DegradedReason.PORTFOLIO_HUB_UNAVAILABLE, str(exc)
+            )
+            _log.warning("get_portfolios failed: %s", exc)
+            return False
+        except Exception as exc:  # noqa: BLE001 - shape/parsing failure
+            self._store.set_degraded(
+                DegradedReason.SNAPSHOT_FETCH_FAILED, exc.__class__.__name__
+            )
+            _log.exception("snapshot fetch shape failure")
+            return False
+
+        self._store.swap(items)
+        try:
+            reconcile_positions(store=self._store, broker=self._broker)
+        except Exception:  # noqa: BLE001
+            _log.exception("reconciliation pass failed")
+        self._last_fired_date = self._clock()
+        return True