feat(hour/day derivation): hour classification, monitoring periods, day aggregates, pruning

Hour classification (PR-4):
- Powered-off: POH delta < 90% of wall-clock span
- Active: DUW delta >= 256 MiB
- Idle: powered on + sampled + below active threshold
- Unknown: unsampled without POH evidence
- Four splits sum to exactly wall_clock_seconds
- Disabled time is never an hour state

Monitoring periods (FL-8):
- ensure_period_open: opens period at run moment if none exists
- close_period: closes with end cause
- is_inside_period: checks timestamp against period bounds
- Never backdated; wall-clock outside periods excluded from denominator

Day aggregates (ST-4, PR-5):
- Derived monotonically from hour rows
- UTC-bounded; no 23/25-hour days
- Coverage: known seconds / period wall-clock
- Gap hours inside periods contribute unknown seconds
- Hours outside periods excluded entirely
- No absent hour interpolated/estimated/fabricated (FL-3)

Raw sample pruning (ST-5):
- Prunes samples older than 14 days
- Hour observations and day aggregates retained indefinitely

Closes #22

src/fenris/monitoring_periods.py

@@ -0,0 +1,124 @@
+"""Monitoring period bookkeeping per spec §5.2, §8.6, §9.8.
+
+A monitoring period is a span during which Fenris monitoring is enabled.
+Powered-off time stays inside a period; deliberately disabled time does not.
+
+Key contracts:
+- Run finding no open period opens one at the run moment, never backdated (§9.8)
+- Wall-clock outside periods excluded from numerator and denominator (§5.2)
+- End causes: user_disabled, migrated, unknown_gap
+"""
+import sqlite3
+from datetime import datetime
+
+
+def ensure_period_open(conn: sqlite3.Connection, run_time: datetime) -> None:
+    """Ensure a monitoring period is open.  If none exists, open one at run_time.
+
+    Spec §9.8: A collection run finding no open monitoring period opens one
+    at the run moment, never backdated.
+    """
+    if get_open_period(conn) is not None:
+        return  # Already open — no-op
+
+    ts = run_time.isoformat()
+    conn.execute(
+        "INSERT INTO monitoring_periods (started_at) VALUES (?)",
+        (ts,),
+    )
+    conn.commit()
+
+
+def close_period(
+    conn: sqlite3.Connection,
+    closed_at: datetime,
+    end_cause: str,
+) -> None:
+    """Close the current open monitoring period.
+
+    Spec §8.6: Pause with an open period closes it user_disabled.
+    If no period is open, this is a no-op (pause otherwise).
+    """
+    open_period = get_open_period(conn)
+    if open_period is None:
+        return  # No-op
+
+    ts = closed_at.isoformat()
+    conn.execute(
+        "UPDATE monitoring_periods SET ended_at = ?, end_cause = ? WHERE id = ?",
+        (ts, end_cause, open_period["id"]),
+    )
+    conn.commit()
+
+
+def get_open_period(conn: sqlite3.Connection) -> dict | None:
+    """Return the currently open monitoring period, or None."""
+    cursor = conn.execute(
+        "SELECT id, started_at, ended_at, end_cause "
+        "FROM monitoring_periods WHERE ended_at IS NULL LIMIT 1"
+    )
+    row = cursor.fetchone()
+    if row is None:
+        return None
+    return {
+        "id": row[0],
+        "started_at": row[1],
+        "ended_at": row[2],
+        "end_cause": row[3],
+    }
+
+
+def is_inside_period(conn: sqlite3.Connection, ts: datetime) -> bool:
+    """Check if a timestamp falls inside any monitoring period.
+
+    Spec §5.2: Wall-clock outside periods is excluded from numerator/denominator.
+    """
+    ts_str = ts.isoformat()
+    cursor = conn.execute(
+        "SELECT 1 FROM monitoring_periods "
+        "WHERE started_at <= ? AND (ended_at IS NULL OR ended_at > ?) "
+        "LIMIT 1",
+        (ts_str, ts_str),
+    )
+    return cursor.fetchone() is not None
+
+
+def wall_clock_in_periods(
+    conn: sqlite3.Connection,
+    start: datetime,
+    end: datetime,
+) -> int:
+    """Compute total wall-clock seconds between start and end that fall inside
+    any monitoring period.
+
+    Used for denominator computation (§5.2).
+    """
+    start_str = start.isoformat()
+    end_str = end.isoformat()
+
+    cursor = conn.execute(
+        "SELECT started_at, ended_at FROM monitoring_periods "
+        "WHERE ended_at IS NULL OR ended_at > ? "
+        "ORDER BY started_at",
+        (start_str,),
+    )
+
+    total = 0
+    for row in cursor.fetchall():
+        period_start = row[0]
+        period_end = row[1]  # None if open
+
+        # Clip period to [start, end]
+        effective_start = max(period_start, start_str)
+        if period_end is not None:
+            effective_end = min(period_end, end_str)
+        else:
+            effective_end = end_str
+
+        if effective_start < effective_end:
+            # Parse for arithmetic
+            s = datetime.fromisoformat(effective_start)
+            e = datetime.fromisoformat(effective_end)
+            total += int((e - s).total_seconds())
+
+    return total