diff --git a/steam_backlog_enforcer/_budget_view.py b/steam_backlog_enforcer/_budget_view.py index 8854217..3b061fc 100644 --- a/steam_backlog_enforcer/_budget_view.py +++ b/steam_backlog_enforcer/_budget_view.py @@ -158,6 +158,8 @@ def build_rules(rules: PlaytimeRules) -> dict[str, Any]: # 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, + # Unspent Fri-Sun time inherited by today; already inside budget_seconds. + "carry_seconds": rules.carry_seconds, "bonuses": { "base": rules.base_seconds, "workout": rules.workout_seconds, diff --git a/steam_backlog_enforcer/_cmd_playtime.py b/steam_backlog_enforcer/_cmd_playtime.py index 2ad49b4..a6134a3 100644 --- a/steam_backlog_enforcer/_cmd_playtime.py +++ b/steam_backlog_enforcer/_cmd_playtime.py @@ -14,6 +14,7 @@ import os from typing import TYPE_CHECKING from steam_backlog_enforcer._enforce_loop import do_enforce +from steam_backlog_enforcer._gaming_days import gaming_day_key from steam_backlog_enforcer._playtime_block import ( block_targets, mounted_targets, @@ -21,7 +22,6 @@ from steam_backlog_enforcer._playtime_block import ( ) from steam_backlog_enforcer._playtime_state import ( PlaytimeState, - gaming_day_key, load_state, rules_for, save_state, diff --git a/steam_backlog_enforcer/_gaming_days.py b/steam_backlog_enforcer/_gaming_days.py new file mode 100644 index 0000000..0525da3 --- /dev/null +++ b/steam_backlog_enforcer/_gaming_days.py @@ -0,0 +1,147 @@ +"""Gaming-day arithmetic: which day *now* is, and what it inherits. + +A gaming "day" runs 06:00-05:59 local, so late-night sessions count against +the day they started in. + +**Free-day carry-over.** Friday to Monday is one block. Whatever a Friday, +Saturday or Sunday leaves unspent is split evenly, with no strings attached, +across the days still left in that block: + + Fri leftover -> Sat, Sun, Mon (a third each) + Sat leftover -> Sun, Mon (half each) + Sun leftover -> Mon + +Monday's leftover, and any Tuesday-Thursday leftover, is dropped. A day's +leftover is measured against its whole budget *including* what it inherited, +so time carried into Saturday and not played moves on to Sunday and Monday +rather than being lost. + +The ledger lives on ``PlaytimeState`` -- root-owned and immutable -- and never +in ``playtime_history.json``: that file is user-writable, and a stored budget +read from it would let anyone grant themselves unlimited time. + +Everything here is pure: it works on primitives handed to it, so it imports +nothing from the playtime modules and cannot close an import cycle. +""" + +from __future__ import annotations + +from datetime import date, timedelta +from typing import TYPE_CHECKING, Final + +if TYPE_CHECKING: + from datetime import datetime + + from steam_backlog_enforcer._playtime_state import PlaytimeState + +# The gaming day starts here, local time. 05:59 belongs to the previous day. +_DAY_BOUNDARY_HOURS: Final = 6 + +# Weekday (Monday == 0) whose leftover is passed on -> how many later days of +# the Friday-Monday block share it. +_SHARES: Final = {4: 3, 5: 2, 6: 1} + + +def gaming_day_key(now: datetime) -> str: + """Return the ``YYYY-MM-DD`` gaming day containing *now*. + + The boundary is 06:00 local, so 02:00 on the 5th belongs to the 4th. + + Args: + now: Timezone-aware local timestamp. + + Returns: + The gaming day key. + """ + return (now - timedelta(hours=_DAY_BOUNDARY_HOURS)).date().isoformat() + + +def pass_on( + carry: dict[str, float], + *, + outgoing_day: str, + budget: float, + spent: float, + new_day: str, +) -> dict[str, float]: + """Return the carry ledger as it stands once *new_day* begins. + + Shares owed to days before *new_day* are dropped, which both bounds the + ledger and means a day the daemon never saw simply forfeits its share. + + Args: + carry: Day key to seconds owed, as held by the outgoing day. + outgoing_day: The gaming day that just ended; ``""`` if none. + budget: The outgoing day's budget, carry included. + spent: Seconds billed during the outgoing day. + new_day: The gaming day now starting. + + Returns: + The ledger for *new_day*, the outgoing day's leftover added. + """ + owed = {day: seconds for day, seconds in carry.items() if day >= new_day} + if not outgoing_day: + return owed + ended = date.fromisoformat(outgoing_day) + shares = _SHARES.get(ended.weekday(), 0) + leftover = max(0.0, budget - spent) + for offset in range(1, shares + 1): + target = (ended + timedelta(days=offset)).isoformat() + if target >= new_day: + owed[target] = owed.get(target, 0.0) + leftover / shares + return owed + + +def carry_due( + carry: dict[str, float], + *, + stored_day: str, + budget: float, + spent: float, + today: str, +) -> float: + """Return the seconds carried into *today*. + + The stored record may still describe yesterday -- the first tick after + 06:00 resolves the budget before rolling the state over -- so the ledger is + projected forward exactly as ``roll_over`` will do it. + + Args: + carry: The stored ledger. + stored_day: The gaming day the stored record covers. + budget: That day's budget, carry included. + spent: Seconds billed during that day. + today: The current gaming day. + + Returns: + Seconds inherited by *today*, or 0. + """ + owed = ( + carry + if stored_day == today + else pass_on( + carry, outgoing_day=stored_day, budget=budget, spent=spent, new_day=today + ) + ) + return owed.get(today, 0.0) + + +def carry_into(stored: PlaytimeState | None, now: datetime) -> float: + """Return the seconds carried into the gaming day containing *now*. + + Args: + stored: The persisted production state, or ``None`` if unreadable. + now: Local timestamp for this tick. + + Returns: + The carry owed to today; 0 when no state is recorded. + """ + if stored is None: + return 0.0 + return carry_due( + stored.carry, + stored_day=stored.day_key, + budget=stored.budget_seconds, + spent=stored.seconds, + today=gaming_day_key(now), + ) diff --git a/steam_backlog_enforcer/_mcp_gaming_time.py b/steam_backlog_enforcer/_mcp_gaming_time.py index b0a4790..e2b83d8 100644 --- a/steam_backlog_enforcer/_mcp_gaming_time.py +++ b/steam_backlog_enforcer/_mcp_gaming_time.py @@ -12,13 +12,13 @@ import os from typing import Any from steam_backlog_enforcer._budget_view import build_budget_snapshot +from steam_backlog_enforcer._gaming_days import gaming_day_key from steam_backlog_enforcer._mcp_server import ( logger, mcp, ) from steam_backlog_enforcer._playtime import ( PlaytimeState, - gaming_day_key, save_state, ) from steam_backlog_enforcer._playtime_block import release_block @@ -56,6 +56,9 @@ def get_gaming_time() -> dict[str, Any]: "seconds_used": today["seconds_used"], "budget_seconds": today["budget_seconds"], "seconds_remaining": today["seconds_remaining"], + # What earned budget_seconds, Friday-Monday carry-over included. + "budget_reason": rules["budget_reason"], + "carry_seconds": rules["carry_seconds"], "next_warning_seconds": today["next_warning_seconds"], "blocked": today["blocked"], "enforcement": rules["enforcement"], diff --git a/steam_backlog_enforcer/_playtime.py b/steam_backlog_enforcer/_playtime.py index a9d861b..b1c39c9 100644 --- a/steam_backlog_enforcer/_playtime.py +++ b/steam_backlog_enforcer/_playtime.py @@ -33,6 +33,7 @@ import logging import time from typing import TYPE_CHECKING +from steam_backlog_enforcer._gaming_days import gaming_day_key from steam_backlog_enforcer._playtime_block import ( mounted_targets, reconcile, @@ -50,7 +51,6 @@ from steam_backlog_enforcer._playtime_procs import attributed_key, qualifying_pi from steam_backlog_enforcer._playtime_state import ( PlaytimeRules, PlaytimeState, - gaming_day_key, load_state, rules_for, save_state, @@ -93,6 +93,13 @@ def playtime_tick( now = datetime.now(UTC).astimezone() rules = rules_for(config, demo=demo) state = roll_over(_state_or_recover(rules, now=now), day_key=gaming_day_key(now)) + # Recorded every tick, total-block branch included: it is what the next + # 06:00 roll-over measures this day's leftover against. A high-water mark, + # because earners can reset at midnight -- before the gaming day ends -- + # and a 05:59 dip must not erase the evening's earned-but-unspent time. + state = replace( + state, budget_seconds=max(state.budget_seconds, rules.budget_seconds) + ) if is_total_block_active(): # The total block runs `pacman -R steam` every tick; our bind mounts diff --git a/steam_backlog_enforcer/_playtime_budget.py b/steam_backlog_enforcer/_playtime_budget.py index a000458..581fce6 100644 --- a/steam_backlog_enforcer/_playtime_budget.py +++ b/steam_backlog_enforcer/_playtime_budget.py @@ -11,6 +11,7 @@ from dataclasses import replace import logging from typing import TYPE_CHECKING +from steam_backlog_enforcer._gaming_days import pass_on from steam_backlog_enforcer._playtime_state import ( _DELTA_CLAMP_FACTOR, PlaytimeRules, @@ -79,7 +80,9 @@ def roll_over(state: PlaytimeState, *, day_key: str) -> PlaytimeState: """Reset *state* if the gaming day has changed. Pure. ``last_tick_at`` carries across the boundary so the first tick of the - new day measures a sane delta rather than restarting from zero. + new day measures a sane delta rather than restarting from zero, and the carry + ledger crosses it with the outgoing day's leftover added (see + ``_gaming_days``). Args: state: Current accounting state. @@ -90,7 +93,17 @@ def roll_over(state: PlaytimeState, *, day_key: str) -> PlaytimeState: """ if state.day_key == day_key: return state - return PlaytimeState(day_key=day_key, last_tick_at=state.last_tick_at) + return PlaytimeState( + day_key=day_key, + last_tick_at=state.last_tick_at, + carry=pass_on( + state.carry, + outgoing_day=state.day_key, + budget=state.budget_seconds, + spent=state.seconds, + new_day=day_key, + ), + ) def pending_warning(state: PlaytimeState, rules: PlaytimeRules) -> int | None: diff --git a/steam_backlog_enforcer/_playtime_state.py b/steam_backlog_enforcer/_playtime_state.py index 6fafcb9..87a0884 100644 --- a/steam_backlog_enforcer/_playtime_state.py +++ b/steam_backlog_enforcer/_playtime_state.py @@ -1,19 +1,20 @@ """The daily playtime budget: its state, its rules, and its persistence. -A gaming "day" runs 06:00-05:59 local, so late-night sessions count against -the day they started in. State is written atomically and re-read every tick, -which is what lets the enforcer survive a restart mid-session. +Gaming days and the Friday-Monday carry-over live in ``_gaming_days``. State +is written atomically and re-read every tick, which is what lets the enforcer +survive a restart mid-session. """ from __future__ import annotations from dataclasses import dataclass, field, fields -from datetime import datetime, timedelta +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._gaming_days import carry_into from steam_backlog_enforcer._whitelist_locking import ( _try_set_immutable, unlock_for_write, @@ -45,9 +46,6 @@ _SCHEMA_VERSION = 1 # being rewritten. STATE_MODE = 0o644 -# The gaming day starts here, local time. 05:59 belongs to the previous day. -_DAY_BOUNDARY_HOURS = 6 - # Each tick's measured delta is capped at this many tick intervals. Two is the # smallest value that tolerates one skipped tick without inflating the count. _DELTA_CLAMP_FACTOR = 2.0 @@ -96,6 +94,13 @@ class PlaytimeState: """ warned_seconds: list[int] = field(default_factory=list) """Warning thresholds already fired during ``day_key``.""" + budget_seconds: float = 0.0 + """Highest budget in force during ``day_key``, carry included; ``0.0`` if unset. + + What ``roll_over`` measures the outgoing day's leftover against. + """ + carry: dict[str, float] = field(default_factory=dict) + """Day key to seconds carried into it from earlier days of the block.""" def is_blocked(self) -> bool: """Whether the cutoff has engaged for this gaming day. @@ -129,6 +134,7 @@ class PlaytimeRules: leetcode_seconds: float = 0.0 reading_seconds: float = 0.0 budget_reason: str = "" + carry_seconds: float = 0.0 def rules_for(config: Config, *, demo: bool) -> PlaytimeRules: @@ -151,8 +157,14 @@ def rules_for(config: Config, *, demo: bool) -> PlaytimeRules: # life) and _budget_view (which reloads Config per HTTP request) from # reporting different budgets. resolved = None if demo else resolve_budget(config) + # Carry sits on top of the 8h cap: it was earned and not spent, so it + # comes with no strings attached. + now = datetime.now().astimezone() + carry = 0.0 if demo else carry_into(load_state(demo=False), now) return PlaytimeRules( - budget_seconds=_DEMO_BUDGET_SECONDS if resolved is None else resolved.seconds, + budget_seconds=_DEMO_BUDGET_SECONDS + if resolved is None + else resolved.seconds + carry, warn_at=_DEMO_WARN_AT if demo else _WARN_AT, sigkill_after=(_DEMO_SIGKILL_AFTER_SECONDS if demo else _SIGKILL_AFTER_SECONDS), count_launchers=config.count_launcher_processes, @@ -164,24 +176,16 @@ def rules_for(config: Config, *, demo: bool) -> PlaytimeRules: 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, - budget_reason=("demo run" if resolved is None else resolved.reason), + budget_reason=( + "demo run" + if resolved is None + else resolved.reason + + (f", +{carry / 60:.0f}m carried over" if carry > 0 else "") + ), + carry_seconds=carry, ) -def gaming_day_key(now: datetime) -> str: - """Return the ``YYYY-MM-DD`` gaming day containing *now*. - - The boundary is 06:00 local, so 02:00 on the 5th belongs to the 4th. - - Args: - now: Timezone-aware local timestamp. - - Returns: - The gaming day key. - """ - return (now - timedelta(hours=_DAY_BOUNDARY_HOURS)).date().isoformat() - - def state_path(*, demo: bool) -> Path: """Return the state file for a demo or production run. diff --git a/steam_backlog_enforcer/tests/test_budget_view.py b/steam_backlog_enforcer/tests/test_budget_view.py index 7d21ae9..292a61c 100644 --- a/steam_backlog_enforcer/tests/test_budget_view.py +++ b/steam_backlog_enforcer/tests/test_budget_view.py @@ -234,5 +234,6 @@ class TestBuildBudgetSnapshot: "demo", "masked_launchers", "budget_reason", + "carry_seconds", "bonuses", } diff --git a/steam_backlog_enforcer/tests/test_gaming_days.py b/steam_backlog_enforcer/tests/test_gaming_days.py new file mode 100644 index 0000000..3a919a1 --- /dev/null +++ b/steam_backlog_enforcer/tests/test_gaming_days.py @@ -0,0 +1,118 @@ +"""Tests for the Friday-Monday carry-over in _gaming_days.""" + +from __future__ import annotations + +from dataclasses import replace +from datetime import datetime, timedelta, timezone +from unittest.mock import patch + +from steam_backlog_enforcer._gaming_days import carry_due, carry_into, pass_on +from steam_backlog_enforcer._playtime_budget import roll_over +from steam_backlog_enforcer._playtime_state import PlaytimeState, rules_for +from steam_backlog_enforcer.config import Config + +HOUR = 3600.0 +LOCAL = timezone(timedelta(hours=2)) +# 2026-10-01 is a Thursday. +THU, FRI, SAT, SUN, MON, TUE = (f"2026-10-{d:02d}" for d in range(1, 7)) + + +def _leftover(day: str, *, budget: float, spent: float, new_day: str) -> dict: + return pass_on({}, outgoing_day=day, budget=budget, spent=spent, new_day=new_day) + + +class TestPassOn: + """Who inherits a day's unspent budget.""" + + def test_friday_splits_three_ways(self) -> None: + owed = _leftover(FRI, budget=8 * HOUR, spent=7 * HOUR, new_day=SAT) + assert owed == {SAT: 1200.0, SUN: 1200.0, MON: 1200.0} + + def test_saturday_splits_two_ways(self) -> None: + owed = _leftover(SAT, budget=8 * HOUR, spent=7 * HOUR, new_day=SUN) + assert owed == {SUN: 1800.0, MON: 1800.0} + + def test_sunday_goes_to_monday(self) -> None: + assert _leftover(SUN, budget=HOUR, spent=0.0, new_day=MON) == {MON: HOUR} + + def test_monday_and_weekdays_drop_their_leftover(self) -> None: + assert _leftover(MON, budget=HOUR, spent=0.0, new_day=TUE) == {} + assert _leftover(THU, budget=HOUR, spent=0.0, new_day=FRI) == {} + + def test_overspent_day_carries_nothing(self) -> None: + owed = _leftover(SUN, budget=HOUR, spent=2 * HOUR, new_day=MON) + assert owed == {MON: 0.0} + + def test_no_outgoing_day_keeps_only_future_shares(self) -> None: + owed = pass_on( + {FRI: 5.0, SUN: 7.0}, outgoing_day="", budget=0.0, spent=0.0, new_day=SAT + ) + assert owed == {SUN: 7.0} + + def test_a_skipped_day_forfeits_its_share(self) -> None: + owed = _leftover(FRI, budget=3 * HOUR, spent=0.0, new_day=SUN) + assert owed == {SUN: HOUR, MON: HOUR} + + def test_shares_accumulate_with_earlier_ones(self) -> None: + owed = pass_on( + {SUN: 600.0, MON: 600.0}, + outgoing_day=SAT, + budget=HOUR, + spent=0.0, + new_day=SUN, + ) + assert owed == {SUN: 2400.0, MON: 2400.0} + + +class TestCarryDue: + """Today's share, whether or not the stored record has rolled over.""" + + def test_same_day_reads_the_ledger(self) -> None: + due = carry_due({SAT: 60.0}, stored_day=SAT, budget=0.0, spent=0.0, today=SAT) + assert due == 60.0 + + def test_stale_record_is_projected_forward(self) -> None: + due = carry_due({}, stored_day=FRI, budget=4 * HOUR, spent=HOUR, today=SAT) + assert due == HOUR + + +class TestCarryInto: + """Reading the carry off a stored state.""" + + def test_no_state_means_no_carry(self) -> None: + assert carry_into(None, datetime(2026, 10, 3, 10, tzinfo=LOCAL)) == 0.0 + + def test_reads_the_projected_share(self) -> None: + stored = PlaytimeState(day_key=FRI, seconds=HOUR, budget_seconds=4 * HOUR) + assert carry_into(stored, datetime(2026, 10, 3, 10, tzinfo=LOCAL)) == HOUR + + +class TestRollOverCarry: + """roll_over threads the ledger across the 06:00 boundary.""" + + def test_unspent_carry_moves_on(self) -> None: + sat = roll_over( + PlaytimeState(day_key=FRI, seconds=7 * HOUR, budget_seconds=8 * HOUR), + day_key=SAT, + ) + sat = replace(sat, seconds=8 * HOUR, budget_seconds=8 * HOUR + 1200.0) + sun = roll_over(sat, day_key=SUN) + assert sun.carry == {SUN: 1800.0, MON: 1800.0} + + +class TestRulesCarry: + """rules_for adds the carry above the cap and says so.""" + + def test_carry_lands_in_budget_and_reason(self) -> None: + with patch( + "steam_backlog_enforcer._playtime_state.carry_into", return_value=1200.0 + ): + rules = rules_for(Config(), demo=False) + assert rules.carry_seconds == 1200.0 + assert rules.budget_reason.endswith(", +20m carried over") + + def test_demo_never_carries(self) -> None: + with patch( + "steam_backlog_enforcer._playtime_state.carry_into", return_value=1200.0 + ): + assert rules_for(Config(), demo=True).carry_seconds == 0.0 diff --git a/steam_backlog_enforcer/tests/test_playtime.py b/steam_backlog_enforcer/tests/test_playtime.py index 2b4dbb9..c000303 100644 --- a/steam_backlog_enforcer/tests/test_playtime.py +++ b/steam_backlog_enforcer/tests/test_playtime.py @@ -9,9 +9,9 @@ from unittest.mock import patch import pytest +from steam_backlog_enforcer._gaming_days import gaming_day_key from steam_backlog_enforcer._playtime_state import ( PlaytimeState, - gaming_day_key, load_state, rules_for, save_state, diff --git a/web/src/components/BudgetRulesCard.test.tsx b/web/src/components/BudgetRulesCard.test.tsx index 28528e7..d0143cf 100644 --- a/web/src/components/BudgetRulesCard.test.tsx +++ b/web/src/components/BudgetRulesCard.test.tsx @@ -12,6 +12,13 @@ describe('BudgetRulesCard', () => { expect(screen.getByText(/1h 0m, 30m, 10m, 5m remaining/)).toBeInTheDocument() expect(screen.queryByText(/demo/)).toBeNull() expect(screen.queryByText('Masked now')).toBeNull() + expect(screen.queryByText('Carried over')).toBeNull() + }) + + it('shows time carried over from earlier free days', () => { + render() + expect(screen.getByText('Carried over')).toBeInTheDocument() + expect(screen.getByText(/\+20m unspent from earlier free days/)).toBeInTheDocument() }) it('shows the demo mode and masked launchers when they apply', () => { diff --git a/web/src/components/BudgetRulesCard.tsx b/web/src/components/BudgetRulesCard.tsx index a4787fe..5cd850c 100644 --- a/web/src/components/BudgetRulesCard.tsx +++ b/web/src/components/BudgetRulesCard.tsx @@ -16,6 +16,12 @@ export function BudgetRulesCard({ rules }: Props) {
Daily budget
{fmtDuration(rules.budget_seconds)}
+ {rules.carry_seconds > 0 && ( + <> +
Carried over
+
+{fmtDuration(rules.carry_seconds)} unspent from earlier free days
+ + )}
Enforcement
{onOff(rules.enforcement)}
Counts launchers
diff --git a/web/src/test/factories.ts b/web/src/test/factories.ts index c84a725..14b24b9 100644 --- a/web/src/test/factories.ts +++ b/web/src/test/factories.ts @@ -142,6 +142,7 @@ export function makeBudgetRules(over: Partial = {}): BudgetRules { warn_at: [3600, 1800, 600, 300], demo: false, masked_launchers: [], + carry_seconds: 0, ...over, } } diff --git a/web/src/types.ts b/web/src/types.ts index 23ed307..60e9d62 100644 --- a/web/src/types.ts +++ b/web/src/types.ts @@ -173,6 +173,8 @@ export interface BudgetRules { warn_at: number[] demo: boolean masked_launchers: string[] + /** Unspent Fri-Sun time inherited by today; already inside budget_seconds. */ + carry_seconds: number } export interface BudgetSnapshot {