feat(run,config): operating hours window + timezone-aware lifecycle state

Add OperatingHoursCfg (enabled/timezone/weekdays/start_hhmm/stop_hhmm) so the run loop can align with NYSE session hours instead of the user's local wall clock (fixes DST drift between NY and Europe/Bucharest). - Config parses [options.operating_hours] and resolves ZoneInfo at load, fail-fast on invalid tz or weekday names. The tz is cached on _tz_cache so the detection loop pays zero per-tick cost. - LifecycleState tracks user_paused + last_window_state across ticks. - Module-scope _should_skip(now, state, cfg, canary) returns skip reason or None. Weekday check uses datetime.weekday() + a fixed MON..SUN list (locale-free; strftime('%a') is localized). - _maybe_log_transition emits market_open / market_closed once per edge. R2: when last_window_state is None (startup), just seed — do not send a spurious market_open alert when run_live_async launches in-window. - _run_tick consults the lifecycle guard before scheduling the heavy detection thread, so drain + transition logging still happen when the tick is skipped. - CLI flags --tz / --weekdays / --oh-start / --oh-stop override TOML. (Kept distinct from the existing --start-at/--stop-at sleep-until-time semantics to avoid breaking current deployments — deviation noted.) - configs/example.toml documents the new [options.operating_hours] table. Tests: parametrized window matrix (tests #8), transition logging (#9), notification side-effect (#10), R2 #20 startup suppression, R2 #22 locale-independent weekday, plus guards for user_paused / canary precedence and config-parse error paths. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-18 11:59:22 +03:00
parent 8b53b8d3c9
commit 54f55752c1
5 changed files with 519 additions and 1 deletions
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -97,3 +97,59 @@ def test_attach_screenshots_unknown_keys_ignored() -> None:
    }))
    assert cfg.attach_screenshots.arm is False
    # Should not raise even with unknown key
+
+
+# ---------------------------------------------------------------------------
+# Commit 3: AlertBehaviorCfg (fire_on_phase_skip)
+# ---------------------------------------------------------------------------
+
+def test_alerts_default_fire_on_phase_skip_true() -> None:
+    cfg = Config._from_dict(_with_opts({}))
+    assert cfg.alerts.fire_on_phase_skip is True
+
+
+def test_alerts_fire_on_phase_skip_can_be_disabled() -> None:
+    cfg = Config._from_dict(_with_opts({"alerts": {"fire_on_phase_skip": False}}))
+    assert cfg.alerts.fire_on_phase_skip is False
+
+
+# ---------------------------------------------------------------------------
+# Commit 4: OperatingHoursCfg parsing + tz cache
+# ---------------------------------------------------------------------------
+
+def test_operating_hours_default_disabled() -> None:
+    cfg = Config._from_dict(_with_opts({}))
+    assert cfg.operating_hours.enabled is False
+    assert cfg.operating_hours.timezone == "America/New_York"
+    assert cfg.operating_hours._tz_cache is None
+
+
+def test_operating_hours_enabled_caches_tz() -> None:
+    cfg = Config._from_dict(_with_opts({
+        "operating_hours": {
+            "enabled": True,
+            "timezone": "America/New_York",
+            "weekdays": ["MON", "TUE", "WED", "THU", "FRI"],
+            "start_hhmm": "09:30",
+            "stop_hhmm": "16:00",
+        }
+    }))
+    assert cfg.operating_hours.enabled is True
+    assert cfg.operating_hours._tz_cache is not None
+    assert str(cfg.operating_hours._tz_cache) == "America/New_York"
+
+
+def test_operating_hours_invalid_tz_raises_valueerror() -> None:
+    import pytest
+    with pytest.raises(ValueError, match="operating_hours.timezone"):
+        Config._from_dict(_with_opts({
+            "operating_hours": {"enabled": True, "timezone": "Not/A_Zone"},
+        }))
+
+
+def test_operating_hours_invalid_weekday_raises_valueerror() -> None:
+    import pytest
+    with pytest.raises(ValueError, match="weekdays"):
+        Config._from_dict(_with_opts({
+            "operating_hours": {"enabled": True, "weekdays": ["XYZ"]},
+        }))
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -537,3 +537,215 @@ async def test_drain_isolates_dispatch_exceptions(monkeypatch):
    # command_error audit event
    errs = [e for e in ctx.audit.events if e.get("event") == "command_error"]
    assert len(errs) == 1 and errs[0]["action"] == "status"
+
+
+# ---------------------------------------------------------------------------
+# Commit 4: operating hours + LifecycleState transitions
+# ---------------------------------------------------------------------------
+
+from zoneinfo import ZoneInfo as _ZI  # noqa: E402
+import datetime as _dt  # noqa: E402
+
+
+def _oh_cfg(enabled=True, weekdays=("MON", "TUE", "WED", "THU", "FRI"),
+            start="09:30", stop="16:00", tz="America/New_York"):
+    """Build a lightweight cfg-like object with operating_hours populated."""
+    oh = types.SimpleNamespace(
+        enabled=enabled,
+        timezone=tz,
+        weekdays=weekdays,
+        start_hhmm=start,
+        stop_hhmm=stop,
+        _tz_cache=_ZI(tz) if enabled else None,
+    )
+    return types.SimpleNamespace(operating_hours=oh)
+
+
+def _fake_canary(paused=False):
+    return types.SimpleNamespace(is_paused=paused)
+
+
+@pytest.mark.parametrize(
+    "local_dt,expected",
+    [
+        # Monday 09:30 NY — exact open → active (None)
+        (_dt.datetime(2026, 4, 20, 9, 30), None),
+        # Monday 16:00 NY — exact close → inactive (>= stop)
+        (_dt.datetime(2026, 4, 20, 16, 0), "out_of_window_hours"),
+        # Monday 08:00 NY — before open
+        (_dt.datetime(2026, 4, 20, 8, 0), "out_of_window_hours"),
+        # Monday 12:00 NY — active
+        (_dt.datetime(2026, 4, 20, 12, 0), None),
+        # Saturday 12:00 NY — weekend
+        (_dt.datetime(2026, 4, 18, 12, 0), "out_of_window_weekend"),
+        # Sunday 23:00 NY — weekend
+        (_dt.datetime(2026, 4, 19, 23, 0), "out_of_window_weekend"),
+    ],
+)
+def test_operating_hours_skip_matrix(local_dt, expected):
+    """Timezone-aware start/stop + weekday checks."""
+    import atm.main as _main
+
+    cfg = _oh_cfg()
+    tz = cfg.operating_hours._tz_cache
+    now_ts = local_dt.replace(tzinfo=tz).timestamp()
+
+    lifecycle = _main.LifecycleState()
+    result = _main._should_skip(now_ts, lifecycle, cfg, _fake_canary())
+    assert result == expected
+
+
+def test_market_open_close_transitions_logged_once():
+    """Crossing a boundary emits exactly one market_open / market_closed event."""
+    import atm.main as _main
+
+    audit_events = []
+    alerts = []
+
+    class _A:
+        def log(self, e): audit_events.append(e)
+
+    class _N:
+        def send(self, a): alerts.append(a)
+
+    cfg = _oh_cfg()
+    tz = cfg.operating_hours._tz_cache
+    lifecycle = _main.LifecycleState()
+    canary = _fake_canary()
+
+    # Prime as closed (before open, Monday 08:00)
+    pre_open = _dt.datetime(2026, 4, 20, 8, 0, tzinfo=tz).timestamp()
+    skip_pre = _main._should_skip(pre_open, lifecycle, cfg, canary)
+    _main._maybe_log_transition(skip_pre, lifecycle, pre_open, _A(), _N())
+    # First evaluation seeds state, no alert yet.
+    assert lifecycle.last_window_state == "closed"
+    assert alerts == []
+    assert audit_events == []
+
+    # Transition to open
+    mid = _dt.datetime(2026, 4, 20, 12, 0, tzinfo=tz).timestamp()
+    skip_mid = _main._should_skip(mid, lifecycle, cfg, canary)
+    _main._maybe_log_transition(skip_mid, lifecycle, mid, _A(), _N())
+    assert lifecycle.last_window_state == "open"
+    assert len(alerts) == 1
+    assert any(e.get("event") == "market_open" for e in audit_events)
+
+    # Repeated open tick — no duplicate log
+    alerts.clear()
+    audit_events.clear()
+    skip_mid2 = _main._should_skip(mid + 60, lifecycle, cfg, canary)
+    _main._maybe_log_transition(skip_mid2, lifecycle, mid + 60, _A(), _N())
+    assert alerts == []
+    assert audit_events == []
+
+    # Transition to close
+    close = _dt.datetime(2026, 4, 20, 17, 0, tzinfo=tz).timestamp()
+    skip_close = _main._should_skip(close, lifecycle, cfg, canary)
+    _main._maybe_log_transition(skip_close, lifecycle, close, _A(), _N())
+    assert lifecycle.last_window_state == "closed"
+    assert any(e.get("event") == "market_closed" for e in audit_events)
+
+
+def test_market_transition_sends_notification():
+    """market_open / market_closed transitions produce kind=status alerts."""
+    import atm.main as _main
+
+    alerts = []
+
+    class _A:
+        def log(self, e): pass
+
+    class _N:
+        def send(self, a): alerts.append(a)
+
+    cfg = _oh_cfg()
+    tz = cfg.operating_hours._tz_cache
+    lifecycle = _main.LifecycleState(last_window_state="closed")
+
+    mid = _dt.datetime(2026, 4, 20, 12, 0, tzinfo=tz).timestamp()
+    _main._maybe_log_transition(None, lifecycle, mid, _A(), _N())
+    assert len(alerts) == 1
+    assert alerts[0].kind == "status"
+    assert "market" in alerts[0].title.lower() or "piața" in alerts[0].body.lower()
+
+
+def test_startup_in_window_suppresses_market_open():
+    """R2 #20: first evaluation in-window just seeds state; no alert fires."""
+    import atm.main as _main
+
+    alerts = []
+    events = []
+
+    class _A:
+        def log(self, e): events.append(e)
+
+    class _N:
+        def send(self, a): alerts.append(a)
+
+    cfg = _oh_cfg()
+    tz = cfg.operating_hours._tz_cache
+    lifecycle = _main.LifecycleState()  # last_window_state is None
+
+    in_window = _dt.datetime(2026, 4, 20, 12, 0, tzinfo=tz).timestamp()
+    skip = _main._should_skip(in_window, lifecycle, cfg, _fake_canary())
+    assert skip is None
+    _main._maybe_log_transition(skip, lifecycle, in_window, _A(), _N())
+
+    # Seeded silently
+    assert lifecycle.last_window_state == "open"
+    assert alerts == []
+    assert not any(e.get("event") == "market_open" for e in events)
+
+    # Two more ticks, still in-window → no spurious alert
+    for _ in range(2):
+        skip = _main._should_skip(in_window + 60, lifecycle, cfg, _fake_canary())
+        _main._maybe_log_transition(skip, lifecycle, in_window + 60, _A(), _N())
+    assert alerts == []
+
+
+def test_operating_hours_weekday_locale_independent():
+    """R2 #22: weekday check must not depend on process locale (strftime('%a'))."""
+    import locale as _locale
+    import atm.main as _main
+
+    cfg = _oh_cfg()
+    tz = cfg.operating_hours._tz_cache
+    # Saturday 12:00 NY
+    sat = _dt.datetime(2026, 4, 18, 12, 0, tzinfo=tz).timestamp()
+
+    original = _locale.setlocale(_locale.LC_TIME)
+    try:
+        for loc in ("C", "de_DE.UTF-8"):
+            try:
+                _locale.setlocale(_locale.LC_TIME, loc)
+            except _locale.Error:
+                continue  # locale not installed → skip gracefully
+            lifecycle = _main.LifecycleState()
+            result = _main._should_skip(sat, lifecycle, cfg, _fake_canary())
+            assert result == "out_of_window_weekend", (
+                f"locale={loc} returned {result!r}"
+            )
+    finally:
+        try:
+            _locale.setlocale(_locale.LC_TIME, original)
+        except _locale.Error:
+            _locale.setlocale(_locale.LC_TIME, "C")
+
+
+def test_should_skip_user_paused_wins():
+    import atm.main as _main
+    cfg = _oh_cfg()
+    lifecycle = _main.LifecycleState(user_paused=True)
+    # Mid-Monday (in-window) — should still skip because user_paused
+    tz = cfg.operating_hours._tz_cache
+    mid = _dt.datetime(2026, 4, 20, 12, 0, tzinfo=tz).timestamp()
+    assert _main._should_skip(mid, lifecycle, cfg, _fake_canary()) == "user_paused"
+
+
+def test_should_skip_canary_drift_wins_over_window():
+    import atm.main as _main
+    cfg = _oh_cfg()
+    lifecycle = _main.LifecycleState()
+    tz = cfg.operating_hours._tz_cache
+    mid = _dt.datetime(2026, 4, 20, 12, 0, tzinfo=tz).timestamp()
+    assert _main._should_skip(mid, lifecycle, cfg, _fake_canary(paused=True)) == "drift_paused"