steam-backlog-enforcer/steam_backlog_enforcer/_shadow_log.py
Krzysztof kuhy Rudnicki 7721b8716e Group playtime shadow and budget breakdown fields
PlaytimeState keeps its shadow_* keys on disk through a ShadowLedger
group (flat, prefix shadow_); PlaytimeRules carries the per-earner split
in a BudgetBreakdown. The golden round-trip test still passes.

Todo: 9b9342ba

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 08:36:21 +01:00

59 lines
2.1 KiB
Python

"""The shadow verdict in the budget audit log: one record per change.
The game journal (:class:`~steam_backlog_enforcer._playtime_log.TickJournal`)
only writes when the *game* verdict changes, so browsing with no game running
would never show up there. Shadow changes get their own event in the same
``budget.jsonl``, written only when the verdict (paused/leisure/free plus the
billed sources) changes -- no heartbeat; the state file has the running total.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Final
if TYPE_CHECKING:
from steam_backlog_enforcer._playtime_log import BudgetLog
from steam_backlog_enforcer._playtime_state import PlaytimeState
from steam_backlog_enforcer._shadow import ShadowVerdict
EVENT_SHADOW_CHANGE: Final = "shadow_change"
class ShadowJournal:
"""Records the shadow verdict whenever it changes."""
def __init__(self, log: BudgetLog) -> None:
"""Start with nothing observed.
Args:
log: Sink to write through (the game journal's own trail).
"""
self._log = log
self._last: ShadowVerdict | None = None
def observe(self, verdict: ShadowVerdict, state: PlaytimeState) -> None:
"""Record *verdict* with the shadow totals if it differs from the last.
Args:
verdict: This tick's shadow verdict.
state: Accounting state after this tick.
"""
if verdict == self._last:
return
self._last = verdict
remaining = state.shadow.budget_seconds - state.shadow.seconds
self._log.record(
EVENT_SHADOW_CHANGE,
shadow_state=verdict.state,
paused_by=verdict.paused_by,
sources=list(verdict.keys),
day_key=state.day_key,
shadow_seconds=round(state.shadow.seconds, 3),
shadow_budget_seconds=round(state.shadow.budget_seconds, 3),
shadow_remaining_seconds=round(remaining, 3),
shadow_paused_seconds=round(state.shadow.paused_seconds, 3),
shadow_per_source={
k: round(v, 3) for k, v in state.shadow.per_source.items()
},
)