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>
This commit is contained in:
Krzysztof Rudnicki 2026-11-12 08:36:21 +01:00
parent 681ab14481
commit 7721b8716e
17 changed files with 148 additions and 98 deletions

View File

@ -168,12 +168,12 @@ def build_rules(rules: PlaytimeRules) -> dict[str, Any]:
# Read off the rules, never re-resolved: resolving a second time here
# is what would let this view report a budget the daemon is not
# enforcing. See _budget_resolve's "one seam".
"budget_reason": rules.budget_reason,
"budget_reason": rules.breakdown.reason,
"bonuses": {
"base": rules.base_seconds,
"workout": rules.workout_seconds,
"leetcode": rules.leetcode_seconds,
"reading": rules.reading_seconds,
"base": rules.breakdown.base_seconds,
"workout": rules.breakdown.workout_seconds,
"leetcode": rules.breakdown.leetcode_seconds,
"reading": rules.breakdown.reading_seconds,
},
# The registry, in its order: what each earner adds today and what it
# would add once done. The bar renders "+<icon><size>" for every
@ -183,7 +183,7 @@ def build_rules(rules: PlaytimeRules) -> dict[str, Any]:
{
"name": earner.name,
"label": earner.label,
"earned_seconds": rules.earned_seconds.get(earner.name, 0.0),
"earned_seconds": rules.breakdown.earned_seconds.get(earner.name, 0.0),
# A full day pays up to the tutor's 60 credited units.
"bonus_seconds": _most(earner) * 60,
}

View File

@ -75,4 +75,4 @@ def held_shadow_today(stored: PlaytimeState | None, now: datetime) -> float:
"""
if stored is None or stored.day_key != gaming_day_key(now):
return 0.0
return stored.shadow_budget_seconds
return stored.shadow.budget_seconds

View File

@ -103,8 +103,11 @@ def playtime_tick(
state = replace(
state,
budget_seconds=max(state.budget_seconds, rules.budget_seconds),
shadow_budget_seconds=max(
state.shadow_budget_seconds, rules.shadow_budget_seconds
shadow=replace(
state.shadow,
budget_seconds=max(
state.shadow.budget_seconds, rules.shadow_budget_seconds
),
),
)

View File

@ -9,6 +9,8 @@ from __future__ import annotations
from dataclasses import dataclass, field
from steam_backlog_enforcer._flat_record import flat_group
# Unchanged by per-game attribution: `load_state` keeps only keys that are
# dataclass fields, so a record written before `per_game` existed loads with
# the field's empty default. A bump would buy nothing and would route the
@ -16,6 +18,39 @@ from dataclasses import dataclass, field
_SCHEMA_VERSION = 1
@dataclass(frozen=True)
class ShadowLedger:
"""Shadow leisure accounting (C4): measured, never enforced.
No :class:`PlaytimeState` field outside this group is ever written by the
shadow path, and these never feed a cutoff. Stored flat with a
``shadow_`` key prefix (``shadow_seconds``, ...).
"""
seconds: float = 0.0
"""Leisure seconds billed during ``day_key`` (wall clock, once per tick)."""
budget_seconds: float = 0.0
"""Highest ``resolve(leisure=True)`` budget of ``day_key``, in seconds."""
per_source: dict[str, float] = field(default_factory=dict)
"""Source key to shadow seconds; overlapping sources split a tick."""
paused_seconds: float = 0.0
"""Seconds a held locker grab or i3lock paused shadow billing."""
@dataclass(frozen=True)
class BudgetBreakdown:
"""Where one day's budget came from, resolved once per tick."""
base_seconds: float = 0.0
workout_seconds: float = 0.0
leetcode_seconds: float = 0.0
reading_seconds: float = 0.0
earned_seconds: dict[str, float] = field(default_factory=dict)
"""Seconds earned today, by earner name."""
reason: str = ""
"""One line explaining the budget in force."""
@dataclass
class PlaytimeState:
"""Per-gaming-day playtime accounting, persisted between ticks."""
@ -51,22 +86,16 @@ class PlaytimeState:
What ``held_today`` holds the day at when a live re-resolution dips.
"""
# Shadow leisure accounting (C4): measured, never enforced. No field
# above is ever written by the shadow path, and these never feed a cutoff.
shadow_seconds: float = 0.0
"""Leisure seconds billed during ``day_key`` (wall clock, once per tick)."""
shadow_budget_seconds: float = 0.0
"""Highest ``resolve(leisure=True)`` budget of ``day_key``, in seconds."""
shadow_per_source: dict[str, float] = field(default_factory=dict)
"""Source key to shadow seconds; overlapping sources split a tick."""
shadow_paused_seconds: float = 0.0
"""Seconds a held locker grab or i3lock paused shadow billing."""
shadow: ShadowLedger = field(
default_factory=ShadowLedger, metadata=flat_group(ShadowLedger, "shadow_")
)
"""Shadow leisure accounting (C4), stored as the ``shadow_*`` keys."""
def is_blocked(self) -> bool:
"""Whether the cutoff has engaged for this gaming day.
Deliberately a method rather than a field: ``save`` serialises
``self.__dict__``, so a derived field would be persisted and could
Deliberately a method rather than a field: ``save`` serialises every
field, so a derived field would be persisted and could
drift out of step with ``blocked_at``.
"""
return self.blocked_at > 0.0

View File

@ -7,16 +7,21 @@ survive a restart mid-session.
from __future__ import annotations
from dataclasses import dataclass, field, fields
from dataclasses import dataclass, field
from datetime import datetime
import json
import logging
from typing import TYPE_CHECKING
from steam_backlog_enforcer._budget_resolve import resolve_budget
from steam_backlog_enforcer._flat_record import from_flat, to_flat
from steam_backlog_enforcer._gaming_days import held_shadow_today, held_today
from steam_backlog_enforcer._playtime_legacy import without_legacy_carry
from steam_backlog_enforcer._playtime_record import _SCHEMA_VERSION, PlaytimeState
from steam_backlog_enforcer._playtime_record import (
_SCHEMA_VERSION,
BudgetBreakdown,
PlaytimeState,
)
from steam_backlog_enforcer._whitelist_locking import (
_try_set_immutable,
unlock_for_write,
@ -26,6 +31,7 @@ from steam_backlog_enforcer.config import CONFIG_DIR, _atomic_write
if TYPE_CHECKING:
from pathlib import Path
from steam_backlog_enforcer._budget_resolve import BudgetResolution
from steam_backlog_enforcer.config import Config
# Explicit because PlaytimeState now lives in _playtime_record: every existing
@ -88,13 +94,8 @@ class PlaytimeRules:
count_launchers: bool
enforcement: bool
demo: bool
# Today's breakdown, carried so it is resolved once; earned_seconds by name.
base_seconds: float = 0.0
workout_seconds: float = 0.0
leetcode_seconds: float = 0.0
reading_seconds: float = 0.0
earned_seconds: dict[str, float] = field(default_factory=dict)
budget_reason: str = ""
# Today's breakdown, carried so it is resolved once.
breakdown: BudgetBreakdown = field(default_factory=BudgetBreakdown)
# The shadow leisure budget (C4), held like budget_seconds; never enforced.
shadow_budget_seconds: float = 0.0
# Phase 2: the billed gaming day is on the leisure budget (set per tick by
@ -132,24 +133,27 @@ def rules_for(config: Config, *, demo: bool) -> PlaytimeRules:
count_launchers=config.playtime.count_launcher_processes,
enforcement=config.playtime.playtime_enforcement,
demo=demo,
base_seconds=_DEMO_BUDGET_SECONDS
if resolved is None
else resolved.base_seconds,
workout_seconds=0.0 if resolved is None else resolved.workout_seconds,
leetcode_seconds=0.0 if resolved is None else resolved.leetcode_seconds,
reading_seconds=0.0 if resolved is None else resolved.reading_seconds,
earned_seconds={} if resolved is None else dict(resolved.earned_seconds),
budget_reason=(
"demo run"
if resolved is None
else resolved.reason + (held_note if held > live else "")
),
breakdown=_breakdown(resolved, held_note if held > live else ""),
shadow_budget_seconds=0.0
if resolved is None
else max(resolved.shadow_seconds, held_shadow_today(stored, now)),
)
def _breakdown(resolved: BudgetResolution | None, held_note: str) -> BudgetBreakdown:
"""The breakdown of *resolved*, or the demo run's when it is ``None``."""
if resolved is None:
return BudgetBreakdown(base_seconds=_DEMO_BUDGET_SECONDS, reason="demo run")
return BudgetBreakdown(
base_seconds=resolved.base_seconds,
workout_seconds=resolved.workout_seconds,
leetcode_seconds=resolved.leetcode_seconds,
reading_seconds=resolved.reading_seconds,
earned_seconds=dict(resolved.earned_seconds),
reason=resolved.reason + held_note,
)
def state_path(*, demo: bool) -> Path:
"""Return the state file for a demo or production run.
@ -190,8 +194,7 @@ def load_state(*, demo: bool) -> PlaytimeState | None:
if not isinstance(data, dict) or data.get("schema_version") != _SCHEMA_VERSION:
logger.warning("Playtime state at %s has an unknown schema.", path)
return None
known = {f.name for f in fields(PlaytimeState)}
state = PlaytimeState(**{k: v for k, v in data.items() if k in known})
state = from_flat(PlaytimeState, data)
return without_legacy_carry(state, data.get("carry"))
@ -210,6 +213,6 @@ def save_state(state: PlaytimeState, *, demo: bool) -> None:
path = state_path(demo=demo)
if not demo:
unlock_for_write(path)
_atomic_write(path, json.dumps(state.__dict__, indent=2) + "\n", mode=STATE_MODE)
_atomic_write(path, json.dumps(to_flat(state), indent=2) + "\n", mode=STATE_MODE)
if not demo:
_try_set_immutable(path, immutable=True)

View File

@ -173,16 +173,19 @@ def shadow_accumulate(
return state
credited = min(delta, interval * _DELTA_CLAMP_FACTOR)
if verdict.paused_by is not None:
paused = state.shadow_paused_seconds + credited
return replace(state, shadow_paused_seconds=paused)
paused = state.shadow.paused_seconds + credited
return replace(state, shadow=replace(state.shadow, paused_seconds=paused))
if not verdict.keys:
return state
share = credited / len(verdict.keys)
per_source = dict(state.shadow_per_source)
per_source = dict(state.shadow.per_source)
for key in verdict.keys:
per_source[key] = per_source.get(key, 0.0) + share
return replace(
state,
shadow_seconds=state.shadow_seconds + credited,
shadow_per_source=per_source,
shadow=replace(
state.shadow,
seconds=state.shadow.seconds + credited,
per_source=per_source,
),
)

View File

@ -41,18 +41,18 @@ class ShadowJournal:
if verdict == self._last:
return
self._last = verdict
remaining = state.shadow_budget_seconds - state.shadow_seconds
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_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_paused_seconds=round(state.shadow.paused_seconds, 3),
shadow_per_source={
k: round(v, 3) for k, v in state.shadow_per_source.items()
k: round(v, 3) for k, v in state.shadow.per_source.items()
},
)

View File

@ -22,12 +22,12 @@ def shadow_view(state: PlaytimeState) -> dict[str, Any]:
Used/budget/remaining seconds, whether the leisure budget would block
now, paused seconds, and the per-source split.
"""
remaining = max(0.0, state.shadow_budget_seconds - state.shadow_seconds)
remaining = max(0.0, state.shadow.budget_seconds - state.shadow.seconds)
return {
"seconds_used": round(state.shadow_seconds, 1),
"budget_seconds": state.shadow_budget_seconds,
"seconds_used": round(state.shadow.seconds, 1),
"budget_seconds": state.shadow.budget_seconds,
"seconds_remaining": round(remaining, 1),
"would_block": remaining <= 0.0,
"paused_seconds": round(state.shadow_paused_seconds, 1),
"per_source": {k: round(v, 1) for k, v in state.shadow_per_source.items()},
"paused_seconds": round(state.shadow.paused_seconds, 1),
"per_source": {k: round(v, 1) for k, v in state.shadow.per_source.items()},
}

View File

@ -192,14 +192,14 @@ class TestReadingReachesTheRulesAndTheView:
return_value=resolution,
):
rules = rules_for(Config(), demo=False)
assert rules.reading_seconds == HOUR
assert rules.breakdown.reading_seconds == HOUR
with patch.object(view, "mounted_targets", return_value=set()):
bonuses = view.build_rules(rules)["bonuses"]
assert bonuses["reading"] == HOUR
def test_a_demo_run_earns_no_reading(self) -> None:
"""A demo run never earns the reading hour."""
assert rules_for(Config(), demo=True).reading_seconds == 0.0
assert rules_for(Config(), demo=True).breakdown.reading_seconds == 0.0
def test_a_resolution_defaults_to_no_reading(self) -> None:
"""A resolution built without reading defaults to zero."""

View File

@ -9,6 +9,7 @@ from datetime import datetime
from steam_backlog_enforcer._budget_view import build_rules
from steam_backlog_enforcer._ledger_earners import registry_for
from steam_backlog_enforcer._playtime_record import BudgetBreakdown
from steam_backlog_enforcer._playtime_state import PlaytimeRules
@ -21,7 +22,7 @@ def test_earners_list_the_registry_with_earned_and_size() -> None:
count_launchers=False,
enforcement=True,
demo=False,
earned_seconds={"leetcode": 3600.0},
breakdown=BudgetBreakdown(earned_seconds={"leetcode": 3600.0}),
)
listed = {e["name"]: e for e in build_rules(rules)["earners"]}
# The registry in force today (the tutor cutover switches it).

View File

@ -109,7 +109,7 @@ class TestRulesHold:
):
rules = rules_for(Config(), demo=False)
assert rules.budget_seconds == 10 * HOUR
assert rules.budget_reason.endswith("; held at 10.0h (earned earlier today)")
assert rules.breakdown.reason.endswith("; held at 10.0h (earned earlier today)")
def test_a_higher_live_answer_wins_silently(self) -> None:
"""A live budget above the held one wins with no held note."""
@ -118,4 +118,4 @@ class TestRulesHold:
):
rules = rules_for(Config(), demo=False)
assert rules.budget_seconds > HOUR
assert "held at" not in rules.budget_reason
assert "held at" not in rules.breakdown.reason

View File

@ -152,7 +152,7 @@ class TestLeisureBilled:
tick = Tick(now=now, interval=3.0, owners={}, verdict=verdict)
state = leisure_billed(state, tick)
moved = state.seconds - before.seconds
assert moved == state.shadow_seconds - before.shadow_seconds
assert moved == state.shadow.seconds - before.shadow.seconds
class TestDormantBilling:

View File

@ -108,7 +108,7 @@ class TestDormant:
state, spy = _tick({})
assert spy.calls == []
# Games-only, exactly as before: the fail-closed shadow does not bill.
assert (state.seconds, state.shadow_seconds) == (0.0, 3.0)
assert (state.seconds, state.shadow.seconds) == (0.0, 3.0)
def test_games_still_bill_games_only(self) -> None:
"""A running game is billed per game as before."""
@ -130,8 +130,8 @@ class TestLive:
"""The fail-closed shadow count becomes the billed count."""
_go_live(tmp_path)
state, spy = _tick({})
assert state.seconds == state.shadow_seconds == 3.0
assert state.shadow_per_source == {_shadow.FAILCLOSED_KEY: 3.0}
assert state.seconds == state.shadow.seconds == 3.0
assert state.shadow.per_source == {_shadow.FAILCLOSED_KEY: 3.0}
assert len(spy.calls) == 1
_seen, rules = spy.calls[0]
assert rules.leisure
@ -141,7 +141,7 @@ class TestLive:
_go_live(tmp_path)
with patch.object(_shadow, "paused_by", return_value="i3lock"):
state, _ = _tick({7: "app:440"})
assert (state.seconds, state.shadow_paused_seconds) == (0.0, 3.0)
assert (state.seconds, state.shadow.paused_seconds) == (0.0, 3.0)
def test_at_zero_the_cutoff_says_leisure_and_kills_run(
self, tmp_path: Path, notify: MagicMock

View File

@ -9,6 +9,7 @@ from leisure_watch.facts import Focus, Now, Reason
import pytest
from steam_backlog_enforcer import _shadow
from steam_backlog_enforcer._playtime_record import ShadowLedger
from steam_backlog_enforcer._playtime_state import PlaytimeState
from steam_backlog_enforcer._shadow import (
FAILCLOSED_KEY,
@ -142,9 +143,9 @@ class TestShadowAccumulate:
def test_paused_goes_to_paused_seconds_only(self) -> None:
"""A paused tick only adds to paused seconds."""
out = self._bill(_state(), ShadowVerdict("i3lock", ()))
assert out.shadow_paused_seconds == 3.0
assert out.shadow_seconds == 0.0
assert out.shadow_per_source == {}
assert out.shadow.paused_seconds == 3.0
assert out.shadow.seconds == 0.0
assert out.shadow.per_source == {}
def test_free_bills_nothing(self) -> None:
"""A free tick leaves the state unchanged."""
@ -154,16 +155,16 @@ class TestShadowAccumulate:
def test_one_source_takes_the_whole_tick(self) -> None:
"""A single source is billed the whole tick."""
out = self._bill(_state(), ShadowVerdict(None, ("app:440",)))
assert out.shadow_seconds == 3.0
assert out.shadow_per_source == {"app:440": 3.0}
assert out.shadow.seconds == 3.0
assert out.shadow.per_source == {"app:440": 3.0}
def test_overlapping_sources_bill_once_and_split(self) -> None:
"""Overlapping sources share one tick, never billing it twice."""
state = _state(shadow_per_source={"a": 1.0}, shadow_seconds=1.0)
state = _state(shadow=ShadowLedger(per_source={"a": 1.0}, seconds=1.0))
out = self._bill(state, ShadowVerdict(None, ("a", "b")))
assert out.shadow_seconds == 4.0
assert out.shadow_per_source == {"a": 2.5, "b": 1.5}
assert sum(out.shadow_per_source.values()) <= out.shadow_seconds + 1e-9
assert out.shadow.seconds == 4.0
assert out.shadow.per_source == {"a": 2.5, "b": 1.5}
assert sum(out.shadow.per_source.values()) <= out.shadow.seconds + 1e-9
def test_the_delta_is_clamped_like_the_enforced_one(self) -> None:
"""A long gap is clamped exactly like the enforced budget."""
@ -173,7 +174,7 @@ class TestShadowAccumulate:
interval=3.0,
verdict=ShadowVerdict(None, (FAILCLOSED_KEY,)),
)
assert out.shadow_seconds == 6.0
assert out.shadow.seconds == 6.0
def test_never_touches_enforced_fields(self) -> None:
"""Shadow billing leaves every enforced field as it was."""

View File

@ -16,6 +16,7 @@ from steam_backlog_enforcer import _mcp_gaming_time as mcp_gaming_time
from steam_backlog_enforcer._budget_resolve import resolve_budget
from steam_backlog_enforcer._gaming_days import held_shadow_today
from steam_backlog_enforcer._playtime import playtime_tick
from steam_backlog_enforcer._playtime_record import ShadowLedger
from steam_backlog_enforcer._playtime_state import (
PlaytimeState,
load_state,
@ -84,12 +85,16 @@ class TestHeldShadow:
def test_same_day_holds_the_high_water(self) -> None:
"""A stored budget from today is held."""
stored = PlaytimeState(day_key=_TODAY, shadow_budget_seconds=9 * HOUR)
stored = PlaytimeState(
day_key=_TODAY, shadow=ShadowLedger(budget_seconds=9 * HOUR)
)
assert held_shadow_today(stored, _NOW) == 9 * HOUR
def test_another_day_or_no_state_holds_nothing(self) -> None:
"""A budget from another day, or none at all, holds nothing."""
stored = PlaytimeState(day_key="2026-07-26", shadow_budget_seconds=HOUR)
stored = PlaytimeState(
day_key="2026-07-26", shadow=ShadowLedger(budget_seconds=HOUR)
)
assert held_shadow_today(stored, _NOW) == 0.0
assert held_shadow_today(None, _NOW) == 0.0
@ -135,9 +140,9 @@ class TestShadowTick:
state = load_state(demo=False)
assert state is not None
assert (state.seconds, state.per_game) == (3.0, {"app:440": 3.0})
assert state.shadow_seconds == 3.0
assert state.shadow_per_source == {"app:440": 3.0}
assert state.shadow_budget_seconds > 0.0
assert state.shadow.seconds == 3.0
assert state.shadow.per_source == {"app:440": 3.0}
assert state.shadow.budget_seconds > 0.0
def test_no_game_and_no_watcher_fails_closed(self) -> None:
"""With no game and no watcher the shadow bills the fail-closed key."""
@ -145,15 +150,15 @@ class TestShadowTick:
state = load_state(demo=False)
assert state is not None
assert state.seconds == 0.0
assert state.shadow_per_source == {_shadow.FAILCLOSED_KEY: 3.0}
assert state.shadow.per_source == {_shadow.FAILCLOSED_KEY: 3.0}
def test_no_shadow_under_a_total_block(self) -> None:
"""A total block bills no shadow seconds but keeps the budget."""
self._tick({}, total_block=True)
state = load_state(demo=False)
assert state is not None
assert state.shadow_seconds == 0.0
assert state.shadow_budget_seconds > 0.0
assert state.shadow.seconds == 0.0
assert state.shadow.budget_seconds > 0.0
def test_the_session_journals_the_shadow_verdict(self) -> None:
"""The tick journals the shadow verdict through the session."""
@ -183,10 +188,12 @@ class TestShadowViews:
stored = PlaytimeState(
day_key=_TODAY,
seconds=10.0,
shadow_seconds=40.0,
shadow_budget_seconds=100.0,
shadow_per_source={"app:440": 40.0},
shadow_paused_seconds=5.0,
shadow=ShadowLedger(
seconds=40.0,
budget_seconds=100.0,
per_source={"app:440": 40.0},
paused_seconds=5.0,
),
)
with (
patch.object(budget_view, "load_state", return_value=stored),
@ -204,7 +211,7 @@ class TestShadowViews:
def test_would_block_at_zero(self) -> None:
"""A spent shadow budget reports would_block with zero remaining."""
stored = PlaytimeState(shadow_seconds=100.0, shadow_budget_seconds=100.0)
stored = PlaytimeState(shadow=ShadowLedger(seconds=100.0, budget_seconds=100.0))
shadow = budget_view.build_today(stored, rules_for(Config(), demo=True))
assert shadow["shadow"]["would_block"] is True
assert shadow["shadow"]["seconds_remaining"] == 0.0

View File

@ -147,7 +147,7 @@ def test_tick_completes_and_enforced_count_is_untouched(
state = load_state(demo=False)
assert state.seconds == seconds
assert state.last_tick_at == T0
assert state.shadow_per_source == {shadow: 3.0}
assert state.shadow.per_source == {shadow: 3.0}
def test_errors_older_than_the_window_are_forgotten() -> None:

View File

@ -7,16 +7,19 @@ import json
from steam_backlog_enforcer import _playtime_log as log_mod
from steam_backlog_enforcer._budget_log_tail import last_verdict
from steam_backlog_enforcer._playtime_log import BudgetLog
from steam_backlog_enforcer._playtime_record import ShadowLedger
from steam_backlog_enforcer._playtime_state import PlaytimeState
from steam_backlog_enforcer._shadow import ShadowVerdict
from steam_backlog_enforcer._shadow_log import EVENT_SHADOW_CHANGE, ShadowJournal
_STATE = PlaytimeState(
day_key="2026-10-19",
shadow_seconds=30.0,
shadow_budget_seconds=36000.0,
shadow_per_source={"app:440": 30.0},
shadow_paused_seconds=6.0,
shadow=ShadowLedger(
seconds=30.0,
budget_seconds=36000.0,
per_source={"app:440": 30.0},
paused_seconds=6.0,
),
)