---
phase: 07-heartbeat-unified-per-symbol-view
plan: 01
subsystem: monitoring
tags: [heartbeat, telegram, junction, stathera, per-symbol-health]

# Dependency graph
requires:
  - phase: 04-heartbeat-all-symbols
    provides: get_heartbeat_symbols() dynamic registry lookup in config.py
provides:
  - Unified Per-Symbol Health section in heartbeat Telegram message
  - Per-symbol TID delta computation in junction.py
  - Exception-only display (one summary line when all clean)
affects: [heartbeat, deploy]

# Tech tracking
tech-stack:
  added: []
  patterns: ["exception-only Telegram display: expand only problematic items"]

key-files:
  created: []
  modified:
    - scripts/heartbeat/checks/junction.py
    - scripts/heartbeat/formatter.py

key-decisions:
  - "Junction deltas stored as junction_delta_{symbol} keys (int or 'partial')"
  - "Journal fallback marks junction_available='journal_only' since it lacks per-symbol granularity"
  - "Removed HEARTBEAT_PRIORITY_SYMBOLS import from formatter (only get_heartbeat_symbols used)"

patterns-established:
  - "Exception-only sections: show one summary line when all items are clean, expand only problematic items"

requirements-completed: [HB-VIEW-01, HB-VIEW-02]

# Metrics
duration: 2min
completed: 2026-03-25
---

# Phase 07 Plan 01: Heartbeat Unified Per-Symbol View Summary

**Merged Yesterday + Junction heartbeat sections into exception-only Per-Symbol Health display with per-symbol TID delta computation**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-25T19:03:59Z
- **Completed:** 2026-03-25T19:06:20Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments

- Junction check refactored from raw TID string dumps to per-symbol delta computation (delta=0 means clean handoff)
- Yesterday + Junction merged into single "Per-Symbol Health" section with exception-only display
- When all 17+ symbols are clean: one summary line instead of ~40 lines of raw TIDs
- Only problematic symbols expanded with specific issue detail (yesterday mismatch, junction gap/overlap)

## Task Commits

Each task was committed atomically:

1. **Task 1: Refactor junction.py to compute per-symbol TID deltas** - `0fcf4f1` (feat)
2. **Task 2: Merge Yesterday + Junction into unified exception-only section in formatter** - `b35c03b` (feat)

## Files Created/Modified

- `scripts/heartbeat/checks/junction.py` - Per-symbol TID delta computation replacing aggregated raw TID strings
- `scripts/heartbeat/formatter.py` - Unified Per-Symbol Health section replacing separate Yesterday and Junction sections

## Decisions Made

- Junction deltas stored as `junction_delta_{symbol}` keys in results dict (int value or "partial" string)
- Journal fallback simplified: marks `junction_available='journal_only'` since journalctl only provides aggregate data without per-symbol granularity
- Removed `HEARTBEAT_PRIORITY_SYMBOLS` import from formatter entirely; `get_heartbeat_symbols()` is the sole symbol source for the unified section

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

- Ruff linter flagged two style issues (PLR1714 merged comparisons, C401 set comprehension) -- fixed inline before commit.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Heartbeat unified view complete. Ready for deploy to bigblack.
- No blockers or concerns.

## Self-Check: PASSED

---

_Phase: 07-heartbeat-unified-per-symbol-view_
_Completed: 2026-03-25_
