steam-backlog-enforcer/steam_backlog_enforcer/_assignment_progress.py
Krzysztof kuhy Rudnicki 681ab14481 Group Config and State fields, keep flat JSON
Config moves the earned-time transports into EarnSources and the budget
switches into PlaytimePolicy; State moves the legacy single pick into
LegacyManualPick and the assignment clocks into AssignmentTimes.
_flat_record writes groups inline at their old position, so config.json
and state.json keep their exact bytes (golden round-trip tests).

Todo: 9b9342ba

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

163 lines
6.0 KiB
Python

"""The "earn one new achievement" release rule, and the bookkeeping behind it.
A game (the current assignment or a manual pick) no longer has to reach 100%
achievements before the user may move on: one achievement unlocked after the
game was assigned is enough. Requiring 100% kept the user stuck on one game for
weeks, which proved ineffective.
``State.finished_app_ids`` still means *100% complete* and nothing else, so the
stats built on it stay honest. A game released below 100% goes back into the
pool behind a cooldown and is ordered least-recently-assigned-first, so it
comes round again only after the rest of the backlog has had a turn.
Leaf, stdout-free module: safe for the MCP server and importable from
``config.py`` without a cycle.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import TYPE_CHECKING
from steam_backlog_enforcer._allowed_games import active_manual_picks
if TYPE_CHECKING:
from steam_backlog_enforcer.config import State
from steam_backlog_enforcer.steam_api import AchievementInfo, GameInfo
# Days a released game stays out of the auto-assignment pool; matches the
# "n = skip" answer of the done prompt.
RELEASE_COOLDOWN_DAYS = 7
def _now_iso() -> str:
return datetime.now(UTC).isoformat()
def iso_to_epoch(iso: str) -> float | None:
"""Return *iso* as epoch seconds, or ``None`` when empty or malformed."""
if not iso:
return None
try:
return datetime.fromisoformat(iso).timestamp()
except ValueError:
return None
def record_assignment(
state: State, app_id: int, game_name: str, at: str | None = None
) -> None:
"""Make *app_id* the current assignment, stamping when it happened.
The single writer of ``current_assigned_at`` and ``last_assigned_at``, so
every assignment path starts the "new achievement" clock the same way.
Does not save.
Args:
state: The enforcer state to mutate.
app_id: The newly assigned game.
game_name: Its display name.
at: ISO timestamp of the assignment; defaults to now.
"""
stamp = at or _now_iso()
state.current_app_id = app_id
state.current_game_name = game_name
state.assignment.current_assigned_at = stamp
state.assignment.last_assigned_at[str(app_id)] = stamp
if not state.enforcement_started_at:
state.enforcement_started_at = stamp
def last_assigned_epoch(state: State, app_id: int) -> float:
"""Return when *app_id* was last assigned, ``0.0`` if never (sorts first)."""
return iso_to_epoch(state.assignment.last_assigned_at.get(str(app_id), "")) or 0.0
def assignment_baseline(state: State, app_id: int) -> str:
"""Return the ISO time after which a new achievement on *app_id* counts.
An active manual pick counts from its own ``started_at`` (a released or
expired one must not: its old unlocks would release a later assignment of
the same game at once); otherwise the current
assignment counts from ``current_assigned_at``. Anything else has no
baseline (``""``), which never releases.
"""
for pick in active_manual_picks(state):
if pick.get("app_id") == app_id and pick.get("started_at"):
return str(pick["started_at"])
if app_id == state.current_app_id:
return state.assignment.current_assigned_at
return ""
def newest_unlock_since(game: GameInfo, since_iso: str) -> AchievementInfo | None:
"""Return the most recent achievement unlocked after *since_iso*, if any.
An empty or malformed baseline returns ``None``: for an enforcement tool,
an unknown start must never read as progress.
"""
since = iso_to_epoch(since_iso)
if since is None:
return None
fresh = [a for a in game.achievements if a.achieved and a.unlock_time > since]
return max(fresh, key=lambda a: a.unlock_time) if fresh else None
def release_verdict(state: State, game: GameInfo) -> tuple[bool, str]:
"""Judge *game* against the release rule: 100%, or one new achievement.
Args:
state: The enforcer state (for the assignment baseline).
game: Freshly refreshed achievement data for the game.
Returns:
Whether the user may move on, and a one-line reason for the CLI.
"""
baseline = assignment_baseline(state, game.app_id)
newest = newest_unlock_since(game, baseline)
if game.is_complete:
return True, f"COMPLETED: {game.name} (100% achievements)!"
if newest is not None:
return True, f"NEW ACHIEVEMENT on {game.name}: '{newest.display_name}'!"
since = baseline[:10] if baseline else "its assignment"
return False, (
f"No new achievement since {since}. Earn at least one to move on. Keep going!"
)
def mark_finished(state: State, app_id: int) -> bool:
"""Record *app_id* as 100% finished, without duplicating an existing record.
The single place a completion is written, so the manual-pick sweep and the
``done``/``check`` paths cannot both append the same id.
Args:
state: The enforcer state to mutate (not saved here).
app_id: The completed app id.
Returns:
Whether this call actually added the id.
"""
if app_id in state.finished_app_ids:
return False
state.finished_app_ids.append(app_id)
return True
def release_game(state: State, game: GameInfo) -> None:
"""Let the user move on from *game*, which has met the release rule.
Marks it finished only when it really is at 100%, frees any manual-pick
slot it holds, remembers when it was released (for tampering detection),
and puts it on the cooldown so the next pick is a different game. Does not
save and does not reassign.
"""
now = _now_iso()
if game.is_complete:
mark_finished(state, game.app_id)
for pick in state.manual_picks:
if pick.get("app_id") == game.app_id and not pick.get("released_at"):
pick["released_at"] = now
state.assignment.released_at[str(game.app_id)] = now
state.skip_for_days(game.app_id, RELEASE_COOLDOWN_DAYS)