---
phase: 03-heartbeat-telemetry-overhaul
plan: 02
subsystem: monitoring
tags: [heartbeat, telegram, yesterday, junction, telemetry, crossover-tid]

requires:
  - phase: 03-heartbeat-telemetry-overhaul
    provides: "Unified per-symbol Stathera check and stathera_per_symbol result key"
provides:
  - "Yesterday orphan completion check per symbol via crossover TID (TELEM-02)"
  - "Junction telemetry: REST/WS trade IDs, forming bar, committed_floors (TELEM-03)"
  - "Both checks visible in Telegram heartbeat message"
affects: [heartbeat-production, sidecar-diagnostics]

tech-stack:
  added: []
  patterns:
    [
      "Per-symbol yesterday orphan validation via Binance REST midnight crossover TID",
      "Junction telemetry from sidecar HTTP endpoints with journalctl fallback",
    ]

key-files:
  created:
    - scripts/heartbeat/checks/yesterday.py
    - scripts/heartbeat/checks/junction.py
    - tests/test_heartbeat_yesterday_junction.py
  modified:
    - scripts/heartbeat/checks/__init__.py
    - scripts/heartbeat/config.py
    - scripts/heartbeat/formatter.py
    - pyproject.toml

key-decisions:
  - "yesterday_completion is health-gating (mismatch = unhealthy); junction telemetry is informational only"
  - "Added scripts to pytest pythonpath to enable heartbeat module imports in tests"
  - "Junction telemetry uses sidecar HTTP endpoints with journalctl log fallback"

patterns-established:
  - "yesterday_{SYMBOL} result keys for per-symbol orphan completion status"
  - "junction_* result keys for sidecar diagnostic telemetry"

requirements-completed: [TELEM-02, TELEM-03]

duration: 6min
completed: 2026-03-21
---

# Phase 3 Plan 2: Yesterday Completion and Junction Telemetry Summary

**Per-symbol yesterday orphan completion via crossover TID validation, junction telemetry from sidecar HTTP+journal, both visible in Telegram heartbeat**

## Performance

- **Duration:** 6 min
- **Started:** 2026-03-21T14:57:10Z
- **Completed:** 2026-03-21T15:03:10Z
- **Tasks:** 2
- **Files modified:** 6 (+ 3 created)

## Accomplishments

- Yesterday orphan completion check validates that orphan bar's last_agg_trade_id == crossover_tid - 1 per streaming symbol
- Junction telemetry collects REST last TID, WS first TID, forming bar state, committed_floors from sidecar
- Both checks wired into run_checks() orchestrator and displayed in Telegram formatter
- yesterday_completion added to HEALTH_GATE_KEYS (mismatch triggers UNHEALTHY)
- Junction telemetry is purely informational (sidecar down already gated separately)
- 6 tests covering match, mismatch, no orphan, query failure, sidecar up, sidecar down

## Task Commits

Each task was committed atomically:

1. **Task 1: Add yesterday completion and junction telemetry check modules** - `ba5fd56` (test: TDD RED) -> `5d91ebc` (feat: TDD GREEN)
2. **Task 2: Add yesterday completion and junction telemetry sections to formatter** - `d7ff788` (feat)

## Files Created/Modified

- `scripts/heartbeat/checks/yesterday.py` - Per-symbol orphan vs crossover TID validation
- `scripts/heartbeat/checks/junction.py` - REST/WS trade IDs, forming bar, committed_floors from sidecar
- `scripts/heartbeat/checks/__init__.py` - Wire both checks into run_checks()
- `scripts/heartbeat/config.py` - Add yesterday_completion to HEALTH_GATE_KEYS
- `scripts/heartbeat/formatter.py` - Yesterday and Junction sections, remediation hint
- `tests/test_heartbeat_yesterday_junction.py` - 6 tests for both check modules
- `pyproject.toml` - Add scripts to pytest pythonpath

## Decisions Made

- yesterday_completion is health-gating; junction_telemetry is not (sidecar down already covered)
- Added `pythonpath = ["scripts"]` to pytest config for heartbeat module imports (existing heartbeat tests also needed this)
- Junction telemetry tries sidecar HTTP endpoints first, falls back to journalctl log parsing

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Added scripts to pytest pythonpath**

- **Found during:** Task 1 (TDD RED phase)
- **Issue:** `heartbeat` module not importable in pytest -- no `pythonpath` config
- **Fix:** Added `pythonpath = ["scripts"]` to `[tool.pytest.ini_options]` in pyproject.toml
- **Files modified:** pyproject.toml
- **Verification:** Both new and existing heartbeat tests now pass
- **Committed in:** ba5fd56 (Task 1 TDD RED commit)

---

**Total deviations:** 1 auto-fixed (1 blocking)
**Impact on plan:** Essential for test execution. Also fixes pre-existing issue with test_heartbeat_stathera.py.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- All 4 TELEM requirements complete (TELEM-01 through TELEM-04)
- Heartbeat telemetry overhaul phase fully done
- Ready for production deployment to bigblack

## Self-Check: PASSED

All 6 files verified present. All 3 commit hashes verified in git log.

---

_Phase: 03-heartbeat-telemetry-overhaul_
_Completed: 2026-03-21_
