cctally 1.113.0 → 1.115.0

package/bin/_lib_five_hour.py

@@ -11,6 +11,11 @@ drift independently; the regression `bin/cctally-5h-canonical-test`
 pins the cross-shape equivalence (epoch-int → datetime → epoch round-trip
 matches the modulo floor on 600-aligned base epochs).
 
+`latest_five_hour_reading` is the one read-only selection of an account's
+newest five-hour reading (#825/#832 spec 4.7 revision 7): it takes the
+caller's connection and runs one bounded statement, so the module stays free
+of I/O at import time and of sibling imports.
+
 `bin/cctally` re-exports every symbol below so internal call sites and
 SourceFileLoader-based tests/fixtures (`tests/test_blocks_recorded_anchor`,
 `tests/test_five_hour_block_selector`, `tests/test_five_hour_blocks_json`,
@@ -24,6 +29,7 @@ from __future__ import annotations
 
 import datetime as dt
 import math
+from dataclasses import dataclass
 
 
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = 600  # 10 minutes; tolerance band for resets_at jitter
@@ -141,3 +147,123 @@ def _canonical_5h_window_key(
     ):
         return prior_key
     return resets_at_epoch - (resets_at_epoch % _FIVE_HOUR_JITTER_FLOOR_SECONDS)
+
+
+@dataclass(frozen=True)
+class FiveHourReading:
+    """One five-hour reading, every field taken from ONE snapshot row.
+
+    ``resets_at`` is the row's stored ``five_hour_resets_at`` text (``None`` on
+    a hand-built or legacy row that stores only the canonical key) and
+    ``window_key`` its canonical window: the stored key, or the
+    ``_canonical_5h_window_key`` floor of the stored reset for a row that
+    predates the key. ``snapshot_id`` / ``captured_at_utc`` / ``account_key`` identify the
+    row, and ``weekly_observation_held`` says whether its WEEKLY axis was
+    carried forward — its five-hour fields are the writing tick's own either
+    way.
+    """
+
+    percent: float
+    resets_at: "str | None"
+    window_key: int
+    captured_at_utc: str
+    snapshot_id: int
+    account_key: str
+    weekly_observation_held: bool
+
+
+def latest_five_hour_reading(
+    conn,
+    *,
+    account_key: "str | None" = None,
+    as_of_utc: "str | None" = None,
+    captured_at_or_after_utc: "str | None" = None,
+    week_start_date: "str | None" = None,
+    week_start_at_in: "tuple[str, ...] | list[str] | None" = None,
+) -> "FiveHourReading | None":
+    """The newest ``weekly_usage_snapshots`` row carrying a five-hour reading
+    (#825/#832 spec 4.7 revision 7 *Latest five-hour reading*).
+
+    The ONE shared, read-only selection every reader of the newest five-hour
+    value uses. A five-hour credit retires a stale replica in place (its three
+    five-hour columns NULL, its weekly evidence kept), and an ordinary
+    weekly-only reading has the same shape, so either can be the newest row
+    while saying nothing about the five-hour axis. Eligible rows carry a
+    finite, non-negative percent and a resolvable canonical window (the stored
+    ``five_hour_window_key``, else ``_canonical_5h_window_key`` of a parseable
+    ``five_hour_resets_at``; the recorder always writes all three together),
+    held rows included (a held row's five-hour fields are the writing tick's
+    own). Zero is a valid percent. Weekly evidence is NOT selected here: callers select it
+    independently, with their own freshness and held-row rules.
+
+    Every restriction is the CALLER's, applied unchanged:
+
+    - ``account_key``: ``None`` adds no account predicate (the caller's own
+      account-blind contract); a key, including ``unattributed``, scopes the
+      selection to that account, so one account never borrows another's
+      reading.
+    - ``as_of_utc`` / ``captured_at_or_after_utc``: an inclusive capture
+      window, compared as instants.
+    - ``week_start_date`` alone: one week date key. With ``week_start_at_in``:
+      the week whose ``week_start_at`` is one of those texts, or a
+      ``week_start_at``-less row of that date (the current-week reader's
+      scope).
+
+    The selection is one ``LIMIT 1`` statement, so no history-sized sort is
+    materialized. ``None`` means no eligible row.
+    """
+    clauses = [
+        "five_hour_percent IS NOT NULL",
+        "five_hour_percent >= 0",
+        "five_hour_percent <= 1e308",
+        "(five_hour_window_key IS NOT NULL "
+        " OR unixepoch(five_hour_resets_at) IS NOT NULL)",
+    ]
+    params: list = []
+    if account_key is not None:
+        clauses.append("account_key = ?")
+        params.append(account_key)
+    if as_of_utc is not None:
+        clauses.append("unixepoch(captured_at_utc) <= unixepoch(?)")
+        params.append(as_of_utc)
+    if captured_at_or_after_utc is not None:
+        clauses.append("unixepoch(captured_at_utc) >= unixepoch(?)")
+        params.append(captured_at_or_after_utc)
+    if week_start_at_in is not None:
+        texts = tuple(week_start_at_in)
+        if not texts:
+            clauses.append("(week_start_at IS NULL AND week_start_date = ?)")
+        else:
+            clauses.append(
+                "(week_start_at IN (" + ",".join("?" * len(texts)) + ") "
+                "OR (week_start_at IS NULL AND week_start_date = ?))")
+            params.extend(texts)
+        params.append(week_start_date)
+    elif week_start_date is not None:
+        clauses.append("week_start_date = ?")
+        params.append(week_start_date)
+    row = conn.execute(
+        "SELECT id, account_key, captured_at_utc, five_hour_percent, "
+        "       five_hour_resets_at, five_hour_window_key, "
+        "       unixepoch(five_hour_resets_at), weekly_observation_held "
+        "FROM weekly_usage_snapshots WHERE " + " AND ".join(clauses) +
+        " ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+        tuple(params),
+    ).fetchone()
+    if row is None:
+        return None
+    percent = float(row[3])
+    if not math.isfinite(percent) or percent < 0:
+        return None
+    window_key = (
+        int(row[5]) if row[5] is not None
+        else _canonical_5h_window_key(int(row[6])))
+    return FiveHourReading(
+        percent=percent,
+        resets_at=row[4],
+        window_key=window_key,
+        captured_at_utc=row[2],
+        snapshot_id=int(row[0]),
+        account_key=row[1],
+        weekly_observation_held=bool(row[7]),
+    )

package/bin/_lib_fmt.py

@@ -292,6 +292,17 @@ def _fmt_num(n: int) -> str:
     return f"{n:,}"
 
 
+def _fmt_usd_accounting(value: float, places: int) -> str:
+    """`-$71.21`: the sign goes before the currency symbol (#886).
+
+    The CLI convention shared with `_lib_diff_kernel` and `_lib_share`'s
+    MoneyCell: an ASCII hyphen, no `+` for a plain amount, and a sign only
+    when `value < 0` — so a negative zero prints unsigned.
+    """
+    sign = "-" if value < 0 else ""
+    return f"{sign}${abs(value):.{places}f}"
+
+
 def _truncate_num(formatted: str, width: int) -> str:
     """Truncate a formatted number to fit width, replacing tail with '…'."""
     if len(formatted) <= width: