From 2f8cf7d6e5965b4e120f77e113239a3091b8902d Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 21 Nov 2026 21:56:12 +0100 Subject: [PATCH] earned_time: add the LeetCode review top-up A finished coach review pays 20 shutdown minutes, once a day, as a top-up: never a rung, never in the floor, added last and capped at the ceiling (sick days too). A row pays only if signed, sourced, first for its slug ever, and backed by a signed non-manual accepted submission in the guard ledger from the 14 days before. From 2026-11-23. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4 --- earned_time/earned_time/__init__.py | 22 ++ earned_time/earned_time/_ledger.py | 5 +- earned_time/earned_time/_maturity.py | 2 + earned_time/earned_time/_policy.py | 44 ++-- earned_time/earned_time/_registry.py | 14 +- earned_time/earned_time/_resolve.py | 25 +- earned_time/earned_time/_review.py | 234 ++++++++++++++++++ earned_time/earned_time/_sick.py | 21 ++ earned_time/earned_time/tests/_review_rows.py | 98 ++++++++ earned_time/earned_time/tests/test_cli.py | 6 +- .../earned_time/tests/test_review_edges.py | 77 ++++++ .../earned_time/tests/test_review_evidence.py | 194 +++++++++++++++ .../earned_time/tests/test_review_resolve.py | 123 +++++++++ 13 files changed, 821 insertions(+), 44 deletions(-) create mode 100644 earned_time/earned_time/_review.py create mode 100644 earned_time/earned_time/tests/_review_rows.py create mode 100644 earned_time/earned_time/tests/test_review_edges.py create mode 100644 earned_time/earned_time/tests/test_review_evidence.py create mode 100644 earned_time/earned_time/tests/test_review_resolve.py diff --git a/earned_time/earned_time/__init__.py b/earned_time/earned_time/__init__.py index 995cd89..6ea1204 100644 --- a/earned_time/earned_time/__init__.py +++ b/earned_time/earned_time/__init__.py @@ -104,9 +104,22 @@ from earned_time._policy import ( from earned_time._quota import TUTOR_QUOTA_FROM, TUTOR_QUOTA_MINUTES, tutor_quota_for from earned_time._registry import all_earners, earners_for, registries from earned_time._resolve import Base, Resolution, Term, base_for, resolve +from earned_time._review import ( + ACCEPTED_LOOKBACK_DAYS, + GUARD_LEDGER, + REVIEW, + REVIEW_FROM, + REVIEW_LEDGER, + REVIEW_SHUTDOWN_MINUTES, + REVIEW_SOURCE, + guard_ledger_for, + paid_reviews, + review_match, +) from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from __all__ = [ + "ACCEPTED_LOOKBACK_DAYS", "ANKI", "ANKI_WAIVED_FROM", "AUTOMATION", @@ -115,6 +128,7 @@ __all__ = [ "GAMING_BASE_MINUTES", "GAMING_CEILING_MINUTES", "GAMING_UNLIMITED_FROM", + "GUARD_LEDGER", "LADDER", "LADDER_FROM", "LEETCODE", @@ -125,6 +139,11 @@ __all__ = [ "MATURE_MIN_AGE_DAYS", "MATURE_MIN_CREDIT_DAYS", "READING", + "REVIEW", + "REVIEW_FROM", + "REVIEW_LEDGER", + "REVIEW_SHUTDOWN_MINUTES", + "REVIEW_SOURCE", "SHUTDOWN_BASE_MINUTES", "SHUTDOWN_CEILING_MINUTES", "SICK_SHUTDOWN_FLOOR_MINUTES", @@ -160,15 +179,18 @@ __all__ = [ "gaming_base_minutes_for", "gaming_ceiling_minutes_for", "gaming_enforced", + "guard_ledger_for", "ladder_for", "leisure_active", "leisure_from", "maturity", "on_ladder", + "paid_reviews", "penalty_start", "real_credit", "registries", "resolve", + "review_match", "shutdown_ceiling_for", "shutdown_minutes_for", "sick_shutdown_from", diff --git a/earned_time/earned_time/_ledger.py b/earned_time/earned_time/_ledger.py index cdb706c..b9cc6b2 100644 --- a/earned_time/earned_time/_ledger.py +++ b/earned_time/earned_time/_ledger.py @@ -133,7 +133,8 @@ def counting_rows( today. ``gate_off`` defaults to False so a caller that forgets it fails closed: no bonus for a part-paid day. - ``None`` when the key or the ledger cannot be read. + ``None`` when the key or the ledger cannot be read. An earner with + ``evidence`` (the review, 0.23.0) is decided by it instead, on all rows. Raises: ValueError: ``earner`` has no ``match``; its answer is the consumer's. @@ -147,6 +148,8 @@ def counting_rows( rows = read_rows(ledger, earner) if rows is None: return None + if earner.evidence is not None: + return earner.evidence(earner, ledger, key, rows, window) match = earner.match kinds = ROW_KINDS.get(match, _CREDIT_ONLY) if not gate_off: diff --git a/earned_time/earned_time/_maturity.py b/earned_time/earned_time/_maturity.py index 789090d..8405702 100644 --- a/earned_time/earned_time/_maturity.py +++ b/earned_time/earned_time/_maturity.py @@ -136,6 +136,8 @@ def _level(days: list[date], earner: Earner, today: date, reasons: list[str]) -> def _penalty_reason( earner: Earner, start: date | None, first: date | None, *, checked: bool ) -> str: + if earner.topup: + return "a top-up: nothing to cut, never penalised" if earner.penalty_from is None: return "no penalty_from: a pure bonus" if start is not None and first is None: diff --git a/earned_time/earned_time/_policy.py b/earned_time/earned_time/_policy.py index 1808e4c..4ddfb40 100644 --- a/earned_time/earned_time/_policy.py +++ b/earned_time/earned_time/_policy.py @@ -6,16 +6,10 @@ steam-backlog-enforcer (gaming) lives here, once. A consumer never hard-codes an hour; it asks :func:`earned_time.resolve` and applies the answer. **Penalty, then reward.** A gate with ``penalty_from`` lowers the base by -exactly what it pays back, from that day on. Doing the thing restores the old -day; skipping it costs the full amount. The date is the gate's own start, so -the cut never lands before the reward that pays for it -- taking an hour a -reader could not yet earn back was a same-day loss on 2026-09-26. - -**Ceilings stay put.** Adding a penalised earner leaves the best case -unchanged: the base drops by what the new earner adds. - -From ``LADDER_FROM`` shutdown follows the sleep ladder instead -(:mod:`earned_time._ladder`); gaming keeps the penalty derivation unchanged. +exactly what it pays back, from that day on (never before the reward that +pays for it: a same-day loss on 2026-09-26). Ceilings stay put. From +``LADDER_FROM`` shutdown follows the sleep ladder (:mod:`earned_time._ladder`). +The review top-up (``REVIEW``, 0.23.0) lives in :mod:`earned_time._review`. **The registry is per day** (:func:`earners_for`). From ``TUTOR_FROM`` Anki is retired -- neither penalised nor paid -- and the tutor (``TUTOR``) is the @@ -41,6 +35,8 @@ from earned_time._match import ( if TYPE_CHECKING: from collections.abc import Callable + from earned_time._review import RowEvidence + Window = tuple[float, float] # Whether one HMAC-verified ``credit`` row counts for the window. CreditMatch = Callable[[dict[str, object], Window], bool] @@ -103,6 +99,16 @@ class Earner: max_units: int | None = None confirmed_on: date | None = None + @property + def topup(self) -> bool: + """A top-up (0.23.0): no rung, no floor cut, added last and capped.""" + return False + + @property + def evidence(self) -> RowEvidence | None: + """A reader that pays from all rows instead of ``match`` (``_review``).""" + return None + def capped(self, units: int) -> int: """``units`` clamped to ``[0, max_units]``.""" units = max(0, units) @@ -142,8 +148,7 @@ WORKOUT: Final = Earner( ledger=".local/share/workout_locker/ledger.json", match=workout_match, missing_ledger_is_no=True, - # The day of its first verified credit, read off the real ledger on - # 2026-10-09 (earned_time 0.6.0); kuhy had been using the gate for real. + # First verified credit, read off the real ledger (0.6.0, 2026-10-09). confirmed_on=date(2026, 10, 1), ) LEETCODE: Final = Earner( @@ -153,8 +158,7 @@ LEETCODE: Final = Earner( shutdown_minutes=60, ledger=".local/share/leetcode_guard/ledger.json", match=leetcode_match, - # The day of its first verified credit, read off the real ledger on - # 2026-10-09 (earned_time 0.6.0); kuhy had been using the gate for real. + # First verified credit, read off the real ledger (0.6.0, 2026-10-09). confirmed_on=date(2026, 8, 12), ) READING: Final = Earner( @@ -166,8 +170,7 @@ READING: Final = Earner( ledger=".local/share/book_guard/ledger.json", match=reading_match, missing_ledger_is_no=True, - # The day of its first verified credit, read off the real ledger on - # 2026-10-09 (earned_time 0.6.0); kuhy had been using the gate for real. + # First verified credit, read off the real ledger (0.6.0, 2026-10-09). confirmed_on=date(2026, 10, 2), ) ANKI: Final = Earner( @@ -195,18 +198,15 @@ AUTOMATION: Final = Earner( ) # From ``TUTOR_FROM``: the tutor pays per active minute (0.8.0; a 0.7.0 -# 15-minute block row counts 15), 1 gaming minute each, up to 60 a day summed -# across sessions. Anki's 30 is folded in, so the base drops by 60. Named -# ``automation`` (``AUTOMATION_TUTOR``) until 0.9.0; rows carry no earner name, -# so the rename only moved the ledger (copied over, old rows included). +# 15-minute block row counts 15), up to 60 a day; Anki's 30 is folded in. +# Named ``automation`` until 0.9.0 (rows carry no earner name). TUTOR: Final = Earner( name="tutor", label="Tutor", gaming_minutes=1, extra_gaming_minutes=1, max_units=60, - # Pre-ladder values, unused (TUTOR_FROM is not before LADDER_FROM); the - # ladder pays 1 per minute (``TUTOR_LADDER``). + # Pre-ladder values, unused: the ladder pays 1 per minute. shutdown_minutes=1, extra_shutdown_minutes=1, kind="counted", diff --git a/earned_time/earned_time/_registry.py b/earned_time/earned_time/_registry.py index 316af48..605dcc9 100644 --- a/earned_time/earned_time/_registry.py +++ b/earned_time/earned_time/_registry.py @@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, Final from earned_time._focus import FOCUS_WATCH, with_focus from earned_time._ladder import ANKI_WAIVED_FROM, TUTOR_FROM +from earned_time._review import REVIEW, REVIEW_FROM if TYPE_CHECKING: from earned_time._policy import Earner @@ -41,17 +42,25 @@ def earners_for(day: date | None = None) -> tuple[Earner, ...]: Between ``ANKI_WAIVED_FROM`` and ``TUTOR_FROM`` the old registry without Anki and the anki-backed Automation: neither penalised nor paid. From ``TUTOR_FROM`` an active focus project swaps its replaced earners for one - ``focus`` earner (:mod:`earned_time._focus`, 0.19.0). + ``focus`` earner (:mod:`earned_time._focus`, 0.19.0). From + ``REVIEW_FROM`` the review top-up joins it (0.23.0). """ target = day or datetime.now(tz=UTC).astimezone().date() before, tutor = registries() if target >= TUTOR_FROM: - return with_focus(tutor, target) + return with_focus(_with_review(tutor, target), target) if target >= ANKI_WAIVED_FROM: return _without_waived(before) return before +def _with_review(registry: tuple[Earner, ...], day: date) -> tuple[Earner, ...]: + """``registry`` plus ``REVIEW`` from ``REVIEW_FROM``, never twice.""" + if day < REVIEW_FROM or REVIEW in registry: + return registry + return (*registry, REVIEW) + + @cache def _without_waived(registry: tuple[Earner, ...]) -> tuple[Earner, ...]: """``registry`` minus the waived earners; one stable tuple per registry.""" @@ -67,5 +76,6 @@ def all_earners() -> tuple[Earner, ...]: seen: dict[Earner, None] = {} for registry in registries(): seen.update(dict.fromkeys(registry)) + seen[REVIEW] = None seen[FOCUS_WATCH] = None return tuple(seen) diff --git a/earned_time/earned_time/_resolve.py b/earned_time/earned_time/_resolve.py index c1507df..01723f3 100644 --- a/earned_time/earned_time/_resolve.py +++ b/earned_time/earned_time/_resolve.py @@ -33,7 +33,7 @@ from earned_time._maturity import confirmed_start, penalty_start from earned_time._policy import SHUTDOWN_BASE_MINUTES, Earner from earned_time._registry import all_earners, earners_for from earned_time._resolution import Base, Resolution, Term -from earned_time._sick import sick_shutdown_from +from earned_time._sick import sick_or if TYPE_CHECKING: from collections.abc import Mapping @@ -84,11 +84,13 @@ def _shutdown_floor(day: date, earners: tuple[Earner, ...], cut: list[Earner]) - On the ladder: the ceiling minus the most each earner can pay (all of a capped earner's units), so doing everything lands exactly on the ceiling -- but only a pure bonus (no ``penalty_from``) or an earner in ``cut``: a - gate whose penalty has not started cannot lower the floor (0.6.1). Before - it: the old base minus the penalties in force. + gate whose penalty has not started cannot lower the floor (0.6.1), nor can + a top-up (0.23.0). Before it: the old base minus the penalties in force. """ if on_ladder(day): - rungs = (e for e in earners if e.penalty_from is None or e in cut) + rungs = ( + e for e in earners if not e.topup and (e.penalty_from is None or e in cut) + ) return shutdown_ceiling_for(day) - sum( e.shutdown_for(e.max_units or 1, day) for e in rungs ) @@ -167,19 +169,6 @@ def _term(item: Earner, answers: Mapping[str, Answer], day: date) -> Term: ) -def _sick_or(earned: int, terms: list[Term], day: date) -> int: - """A sick day's shutdown: 20:00 plus the paid terms, never below ``earned``. - - The terms are paid at gaming pay before ``GAMING_UNLIMITED_FROM`` and at - their shutdown (rung) pay from it: the gaming budget no longer exists. - """ - if gaming_enforced(day): - paid = sum(t.gaming_minutes for t in terms) - else: - paid = sum(t.shutdown_minutes for t in terms) - return max(earned, sick_shutdown_from(paid, day)) - - def resolve( answers: Mapping[str, Answer], day: date | None = None, @@ -236,7 +225,7 @@ def resolve( shutdown_ceiling_for(target), base.shutdown_minutes + sum(t.shutdown_minutes for t in terms), ) - shutdown = _sick_or(earned, terms, target) if sick else earned + shutdown = sick_or(earned, terms, target) if sick else earned return Resolution( day=target, base=base, diff --git a/earned_time/earned_time/_review.py b/earned_time/earned_time/_review.py new file mode 100644 index 0000000..a1de6c8 --- /dev/null +++ b/earned_time/earned_time/_review.py @@ -0,0 +1,234 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The LeetCode review top-up (0.23.0): which coach review rows pay. + +The coach (``/leetcode review``) signs one ``credit`` row per finished review +in its own ledger. A row pays only if it is signed, its ``detail.source`` is +:data:`REVIEW_SOURCE`, it finished in the day's window, it is the earliest +signed review of its ``detail.title_slug`` (each slug pays once, ever), and +the LeetCode guard's ledger holds a signed, non-manual accepted submission of +that slug from the :data:`ACCEPTED_LOOKBACK_DAYS` before the review finished. + +The review row alone proves nothing (the coach's flag rests on unsigned +heartbeats), so the guard's accepted submission is the evidence and the +once-per-slug rule is the cap on forgery (kuhy, 2026-11-21, Q14). + +**Fail closed, logged.** An unreadable guard ledger is ``None`` ("could not +check", one warning from :func:`~earned_time._ledger.read_rows`); a row with +no slug or no usable ``finished_at`` pays nothing, with a warning. No review +row in the window is an honest "no" and never reads the guard ledger. +""" + +from __future__ import annotations + +from dataclasses import dataclass, replace +from datetime import UTC, date, datetime +import logging +from pathlib import PurePosixPath +from typing import TYPE_CHECKING, Final + +from earned_time._evidence import MANUAL_PREFIXES, MANUAL_SOURCES +from earned_time._ledger import read_rows, verified +from earned_time._policy import Earner + +if TYPE_CHECKING: + from collections.abc import Callable, Iterator + from pathlib import Path + + from earned_time._policy import Window + + # (earner, ledger, key, rows, window) -> the rows that pay, or ``None``. + RowEvidence = Callable[ + [Earner, Path, bytes, list[object], Window], + Iterator[dict[str, object]] | None, + ] + +_logger: Final = logging.getLogger(__name__) + +# The first day the review earner is in the registry: the day after the +# planned deploy (2026-11-22). +REVIEW_FROM: Final = date(2026, 11, 23) +# What the day's first paid review adds to shutdown, capped at the ceiling. +REVIEW_SHUTDOWN_MINUTES: Final = 20 +REVIEW_SOURCE: Final = "leetcode-coach-review" +REVIEW_LEDGER: Final = ".local/share/leetcode-coach/review_ledger.json" +# The LeetCode guard's ledger (``LEETCODE.ledger``), relative to the home. +GUARD_LEDGER: Final = ".local/share/leetcode_guard/ledger.json" +GUARD_SOURCE: Final = "leetcode" +# How old the accepted submission may be when the review finishes. +ACCEPTED_LOOKBACK_DAYS: Final = 14 +_LOOKBACK_SECONDS: Final = ACCEPTED_LOOKBACK_DAYS * 24 * 60 * 60 + + +def _detail(row: dict[str, object]) -> dict[str, object]: + detail = row.get("detail") + return detail if isinstance(detail, dict) else {} + + +def _stamp(raw: object) -> float | None: + """A unix-seconds stamp, or ``None`` when absent or unparsable.""" + try: + return float(str(raw)) + except ValueError: + return None + + +def review_match(row: dict[str, object], window: Window) -> bool: + """A coach review row that finished in ``window``. + + Like ``leetcode_match``: ``finished_at`` decides, the row's ``day`` is the + fallback for a row without a usable stamp (that row still pays nothing: + the lookback needs the stamp, :func:`paid_reviews`). + """ + detail = _detail(row) + if detail.get("source") != REVIEW_SOURCE: + return False + stamp = _stamp(detail.get("finished_at")) + if stamp is not None: + return window[0] <= stamp <= window[1] + local = datetime.fromtimestamp(window[0], tz=UTC).astimezone().date() + return row.get("day") == local.isoformat() + + +def _slug(row: dict[str, object]) -> str | None: + slug = _detail(row).get("title_slug") + return slug if isinstance(slug, str) and slug else None + + +def _manual(row: dict[str, object]) -> bool: + """A guard row a human granted: manual source, id, or ``manual_grant`` note.""" + detail = _detail(row) + return ( + detail.get("source") in MANUAL_SOURCES + or "manual_grant" in detail + or str(row.get("entry_id")).startswith(MANUAL_PREFIXES) + ) + + +def _accepted(rows: list[object], key: bytes) -> dict[str, list[float]]: + """Each slug's signed, non-manual accepted-submission stamps in the guard.""" + found: dict[str, list[float]] = {} + for row in rows: + if not isinstance(row, dict) or row.get("kind") != "credit": + continue + if not verified(row, key) or _manual(row): + continue + detail = _detail(row) + slug = _slug(row) + stamp = _stamp(detail.get("submitted_at")) + if detail.get("source") == GUARD_SOURCE and slug and stamp is not None: + found.setdefault(slug, []).append(stamp) + return found + + +def _order(row: dict[str, object]) -> float: + """When a review happened, for "earliest": ``finished_at``, else ``created_at``.""" + stamp = _stamp(_detail(row).get("finished_at")) + if stamp is not None: + return stamp + try: + return datetime.fromisoformat(str(row.get("created_at"))).timestamp() + except ValueError: + return float("inf") + + +def _firsts(rows: list[dict[str, object]]) -> dict[str, dict[str, object]]: + """The earliest signed review row of each slug (a tie: the first written).""" + firsts: dict[str, dict[str, object]] = {} + for row in sorted(rows, key=_order): + slug = _slug(row) + if slug is not None: + firsts.setdefault(slug, row) + return firsts + + +def guard_ledger_for(ledger: Path, earner: Earner) -> Path: + """The guard ledger under the same home as ``ledger`` (``earner.ledger``). + + The consumer resolves only the review ledger (``home / earner.ledger``), + so the home is that path with ``earner.ledger``'s depth stripped: a test + that redirects the home redirects both ledgers. + """ + depth = len(PurePosixPath(str(earner.ledger)).parts) + return ledger.parents[depth - 1] / GUARD_LEDGER + + +def _pays(row: dict[str, object], accepted: dict[str, list[float]]) -> bool: + """Whether a slug's first review is backed by an accepted submission.""" + finished = _stamp(_detail(row).get("finished_at")) + if finished is None: + _logger.warning( + "LeetCode review %r has no usable finished_at; it pays nothing", + row.get("entry_id"), + ) + return False + slug = str(_slug(row)) + return any( + finished - _LOOKBACK_SECONDS <= t <= finished for t in accepted.get(slug, ()) + ) + + +def paid_reviews( + earner: Earner, ledger: Path, key: bytes, rows: list[object], window: Window +) -> Iterator[dict[str, object]] | None: + """The review rows that pay in ``window``; ``None`` if the guard is unreadable. + + ``earner.evidence`` for :data:`~earned_time.REVIEW`, called by + :func:`~earned_time._ledger.counting_rows` with the review ledger's rows + already read and the key already loaded. + """ + reviews = [ + row + for row in rows + if isinstance(row, dict) + and row.get("kind") == "credit" + and _detail(row).get("source") == REVIEW_SOURCE + and verified(row, key) + ] + today = [row for row in reviews if review_match(row, window)] + if not today: + return iter(()) + guard = replace(earner, label="LeetCode guard", missing_ledger_is_no=False) + guard_rows = read_rows(guard_ledger_for(ledger, earner), guard) + if guard_rows is None: + return None + accepted = _accepted(guard_rows, key) + firsts = _firsts(reviews) + paid: list[dict[str, object]] = [] + for row in today: + slug = _slug(row) + if slug is None: + _logger.warning( + "LeetCode review %r has no title_slug; it pays nothing", + row.get("entry_id"), + ) + elif firsts[slug] is row and _pays(row, accepted): + paid.append(row) + return iter(paid) + + +@dataclass(frozen=True) +class ReviewEarner(Earner): + """The review's earner kind: a top-up paid by :func:`paid_reviews`.""" + + @property + def topup(self) -> bool: + """Always: never a rung, never in the floor, added last and capped.""" + return True + + @property + def evidence(self) -> RowEvidence: + """:func:`paid_reviews`: the guard ledger backs each row.""" + return paid_reviews + + +# A pure top-up: 0 gaming, no penalty, not on the ladder, not in the floor. +# ``confirmed_on`` stays unset until kuhy has seen a real review credited. +REVIEW: Final = ReviewEarner( + name="review", + label="LeetCode review", + gaming_minutes=0, + shutdown_minutes=REVIEW_SHUTDOWN_MINUTES, + ledger=REVIEW_LEDGER, + match=review_match, + missing_ledger_is_no=True, +) diff --git a/earned_time/earned_time/_sick.py b/earned_time/earned_time/_sick.py index d7a19db..2a1a650 100644 --- a/earned_time/earned_time/_sick.py +++ b/earned_time/earned_time/_sick.py @@ -20,11 +20,15 @@ from __future__ import annotations from typing import TYPE_CHECKING, Final +from earned_time._gaming import gaming_enforced from earned_time._ladder import shutdown_ceiling_for if TYPE_CHECKING: + from collections.abc import Sequence from datetime import date + from earned_time._resolution import Term + # 20:00, minutes after local midnight. SICK_SHUTDOWN_FLOOR_MINUTES: Final = 20 * 60 @@ -40,3 +44,20 @@ def sick_shutdown_from(paid_minutes: int, day: date) -> int: ``min(ceiling, SICK_SHUTDOWN_FLOOR_MINUTES + paid_minutes)``. """ return min(shutdown_ceiling_for(day), SICK_SHUTDOWN_FLOOR_MINUTES + paid_minutes) + + +def sick_or(earned: int, terms: Sequence[Term], day: date) -> int: + """A sick day's shutdown: 20:00 plus the paid terms, never below ``earned``. + + The terms are paid at gaming pay before ``GAMING_UNLIMITED_FROM`` and at + their shutdown (rung) pay from it: the gaming budget no longer exists. + A top-up adds its shutdown minutes last, capped (0.23.0). + """ + paying = [t for t in terms if not t.earner.topup] + if gaming_enforced(day): + paid = sum(t.gaming_minutes for t in paying) + else: + paid = sum(t.shutdown_minutes for t in paying) + topup = sum(t.shutdown_minutes for t in terms if t.earner.topup) + lifted = min(shutdown_ceiling_for(day), sick_shutdown_from(paid, day) + topup) + return max(earned, lifted) diff --git a/earned_time/earned_time/tests/_review_rows.py b/earned_time/earned_time/tests/_review_rows.py new file mode 100644 index 0000000..e4e0625 --- /dev/null +++ b/earned_time/earned_time/tests/_review_rows.py @@ -0,0 +1,98 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""A fake home with a coach review ledger and a LeetCode guard ledger.""" + +from __future__ import annotations + +from datetime import date, datetime, time +import json +from typing import TYPE_CHECKING + +from earned_time import GUARD_LEDGER, REVIEW, entry_signature +from earned_time.tests._maturity_rows import KEY, at + +if TYPE_CHECKING: + from pathlib import Path + +# A day the review earner is registered on (REVIEW_FROM is 2026-11-23). +DAY = date(2026, 11, 24) +SLUG = "two-sum" + + +def sign(row: dict[str, object], key: bytes = KEY) -> dict[str, object]: + """``row`` with its HMAC under ``key``.""" + return {**row, "hmac": entry_signature(row, key)} + + +def review( + slug: str | None = SLUG, day: date = DAY, hour: int = 20, **detail: object +) -> dict[str, object]: + """One signed coach row for a finished review, as the coach writes it.""" + fields: dict[str, object] = { + "source": "leetcode-coach-review", + "cause": "slow-solve", + "finished_at": at(day, hour), + **detail, + } + if slug is not None: + fields["title_slug"] = slug + return sign( + { + "entry_id": f"review:{slug}", + "kind": "credit", + "day": day.isoformat(), + "created_at": datetime.combine(day, time(hour)).astimezone().isoformat(), + "amount": 1, + "device": "pc", + "detail": fields, + } + ) + + +def accepted( + slug: str = SLUG, + day: date = DAY, + hour: int = 10, + entry: str | None = None, + **detail: object, +) -> dict[str, object]: + """One signed LeetCode guard credit: an accepted submission of ``slug``.""" + return sign( + { + "entry_id": entry or f"ac:{slug}:{day}:{hour}", + "kind": "credit", + "day": day.isoformat(), + "amount": 1, + "detail": { + "title_slug": slug, + "source": "leetcode", + "submitted_at": at(day, hour), + **detail, + }, + } + ) + + +def write(path: Path, rows: list[dict[str, object]]) -> Path: + """Write ``rows`` as a ``{"version", "entries"}`` ledger at ``path``.""" + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps({"version": 1, "entries": rows}), encoding="utf-8") + return path + + +def home_with( + home: Path, + reviews: list[dict[str, object]], + guard: list[dict[str, object]] | None, +) -> Path: + """Lay both ledgers out under ``home``; returns the review ledger path. + + ``guard=None`` leaves the guard ledger missing. + """ + if guard is not None: + write(home / GUARD_LEDGER, guard) + return write(home / str(REVIEW.ledger), reviews) + + +def evening(day: date = DAY) -> datetime: + """``day`` at 22:00 local: every fixture row of the day lies before it.""" + return datetime.combine(day, time(22)).astimezone() diff --git a/earned_time/earned_time/tests/test_cli.py b/earned_time/earned_time/tests/test_cli.py index 434c816..27913a5 100644 --- a/earned_time/earned_time/tests/test_cli.py +++ b/earned_time/earned_time/tests/test_cli.py @@ -58,9 +58,12 @@ def test_table(home: Path, capsys: pytest.CaptureFixture[str]) -> None: "anki", "automation", "tutor", + "review", } assert rows["leetcode"].split()[1:5] == ["maturing", "1", str(DAY), str(DAY)] assert "not in the registry on 2026-10-09" in rows["anki"] + assert "a top-up: nothing to cut, never penalised" in rows["review"] + assert "not in the registry on 2026-10-09" in rows["review"] assert "could not check: ledger" not in rows["reading"] assert rows["reading"].endswith( "no verified credit but confirmed_on 2026-10-02: " @@ -96,6 +99,7 @@ def test_default_day_and_unregistered_earners( "workout", "reading", "tutor", + "review", ] @@ -142,4 +146,4 @@ def test_a_name_shared_across_registries_gets_its_ledger_dir( monkeypatch.setattr(earned_time, "TUTOR_EARNERS", (new,)) assert cli.main(["maturity", "--day", DAY.isoformat()]) == 0 rows = [line.split()[0] for line in capsys.readouterr().out.splitlines()[2:-1]] - assert rows == ["twin:a", "twin:b"] + assert rows == ["twin:a", "twin:b", "review"] diff --git a/earned_time/earned_time/tests/test_review_edges.py b/earned_time/earned_time/tests/test_review_edges.py new file mode 100644 index 0000000..5fe9de4 --- /dev/null +++ b/earned_time/earned_time/tests/test_review_edges.py @@ -0,0 +1,77 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Review evidence edges (0.23.0): odd rows on either ledger.""" + +from __future__ import annotations + +import json +from typing import TYPE_CHECKING + +from earned_time import ( + GUARD_LEDGER, + REVIEW, + day_window, + done_today, + guard_ledger_for, + review_match, +) +from earned_time.tests._review_rows import ( + DAY, + accepted, + evening, + home_with, + review, + sign, +) + +if TYPE_CHECKING: + from pathlib import Path + + +def _unsigned(row: dict[str, object]) -> dict[str, object]: + return {k: v for k, v in row.items() if k != "hmac"} + + +def test_the_matcher_wants_the_coach_source() -> None: + assert review_match(accepted(), day_window(DAY)) is False + assert review_match(review(), day_window(DAY)) is True + + +def test_a_guard_row_of_another_source_does_not_back_it( + tmp_path: Path, key_file: Path +) -> None: + ledger = home_with(tmp_path, [review()], [accepted(source="escape")]) + assert done_today(REVIEW, ledger, key_file, now=evening()) is False + + +def test_a_guard_row_without_a_stamp_does_not_back_it( + tmp_path: Path, key_file: Path +) -> None: + ledger = home_with(tmp_path, [review()], [accepted(submitted_at="later")]) + assert done_today(REVIEW, ledger, key_file, now=evening()) is False + + +def test_junk_guard_rows_are_skipped(tmp_path: Path, key_file: Path) -> None: + ledger = home_with(tmp_path, [review()], []) + guard = {"entries": ["junk", accepted()]} + (tmp_path / GUARD_LEDGER).write_text(json.dumps(guard), encoding="utf-8") + assert done_today(REVIEW, ledger, key_file, now=evening()) is True + + +def test_a_timeless_review_never_spends_the_slug( + tmp_path: Path, key_file: Path +) -> None: + timeless = sign({**_unsigned(review(finished_at="x")), "created_at": "never"}) + ledger = home_with(tmp_path, [timeless, review()], [accepted()]) + assert done_today(REVIEW, ledger, key_file, now=evening()) is True + + +def test_junk_review_rows_are_skipped(tmp_path: Path, key_file: Path) -> None: + ledger = home_with(tmp_path, [review()], [accepted()]) + text = ledger.read_text(encoding="utf-8").replace('"entries": [', '"entries": [7, ') + ledger.write_text(text, encoding="utf-8") + assert done_today(REVIEW, ledger, key_file, now=evening()) is True + + +def test_the_guard_ledger_shares_the_review_ledgers_home(tmp_path: Path) -> None: + review_ledger = tmp_path / str(REVIEW.ledger) + assert guard_ledger_for(review_ledger, REVIEW) == tmp_path / GUARD_LEDGER diff --git a/earned_time/earned_time/tests/test_review_evidence.py b/earned_time/earned_time/tests/test_review_evidence.py new file mode 100644 index 0000000..96637ce --- /dev/null +++ b/earned_time/earned_time/tests/test_review_evidence.py @@ -0,0 +1,194 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Which coach review rows pay (0.23.0): signed, sourced, backed, first per slug.""" + +from __future__ import annotations + +from datetime import timedelta +import logging +from typing import TYPE_CHECKING + +import pytest + +from earned_time import ( + ACCEPTED_LOOKBACK_DAYS, + GUARD_LEDGER, + LEETCODE, + REVIEW, + credit_units, + done_today, +) +from earned_time.tests._review_rows import ( + DAY, + accepted, + evening, + home_with, + review, + sign, +) + +if TYPE_CHECKING: + from pathlib import Path + + +def _done(home: Path, key_file: Path, reviews: list, guard: list | None) -> object: + ledger = home_with(home, reviews, guard) + return done_today(REVIEW, ledger, key_file, now=evening()) + + +def test_the_guard_ledger_is_the_leetcode_earners() -> None: + assert LEETCODE.ledger == GUARD_LEDGER + + +def test_a_backed_review_pays(tmp_path: Path, key_file: Path) -> None: + assert _done(tmp_path, key_file, [review()], [accepted()]) is True + + +def test_two_reviews_in_a_day_are_one_unit(tmp_path: Path, key_file: Path) -> None: + reviews = [review(), review("add-two-numbers", hour=21)] + guard = [accepted(), accepted("add-two-numbers")] + ledger = home_with(tmp_path, reviews, guard) + assert done_today(REVIEW, ledger, key_file, now=evening()) is True + assert credit_units(REVIEW, ledger, key_file, DAY) == 2 # resolve pays it flat + + +def test_a_forged_row_pays_nothing(tmp_path: Path, key_file: Path) -> None: + forged = sign({k: v for k, v in review().items() if k != "hmac"}, b"other-key") + assert _done(tmp_path, key_file, [forged], [accepted()]) is False + + +def test_an_unsigned_row_pays_nothing(tmp_path: Path, key_file: Path) -> None: + row = {k: v for k, v in review().items() if k != "hmac"} + assert _done(tmp_path, key_file, [row], [accepted()]) is False + + +def test_another_source_pays_nothing(tmp_path: Path, key_file: Path) -> None: + row = review(source="leetcode-coach") + assert _done(tmp_path, key_file, [row], [accepted()]) is False + + +def test_no_accepted_submission_pays_nothing(tmp_path: Path, key_file: Path) -> None: + assert _done(tmp_path, key_file, [review()], [accepted("other")]) is False + + +def test_a_forged_guard_row_does_not_back_it(tmp_path: Path, key_file: Path) -> None: + fake = sign({k: v for k, v in accepted().items() if k != "hmac"}, b"x") + assert _done(tmp_path, key_file, [review()], [fake]) is False + + +@pytest.mark.parametrize( + ("entry", "extra"), + [ + ("manual:2026-11-24", {}), + ("manual_grant:two-sum", {}), + (None, {"source": "manual_grant"}), + (None, {"manual_grant": "ordered by hand"}), + ], +) +def test_a_manual_grant_does_not_back_it( + tmp_path: Path, key_file: Path, entry: str | None, extra: dict[str, object] +) -> None: + guard = [accepted(entry=entry, **extra)] + assert _done(tmp_path, key_file, [review()], guard) is False + + +def test_a_charge_row_does_not_back_it(tmp_path: Path, key_file: Path) -> None: + row = {k: v for k, v in accepted().items() if k != "hmac"} + charge = sign({**row, "kind": "charge"}) + assert _done(tmp_path, key_file, [review()], [charge]) is False + + +def test_a_submission_inside_the_lookback_backs_it( + tmp_path: Path, key_file: Path +) -> None: + old = DAY - timedelta(days=ACCEPTED_LOOKBACK_DAYS) + assert _done(tmp_path, key_file, [review()], [accepted(day=old, hour=21)]) is True + + +def test_a_submission_older_than_the_lookback_pays_nothing( + tmp_path: Path, key_file: Path +) -> None: + old = DAY - timedelta(days=ACCEPTED_LOOKBACK_DAYS + 1) + assert _done(tmp_path, key_file, [review()], [accepted(day=old)]) is False + + +def test_a_submission_after_the_review_pays_nothing( + tmp_path: Path, key_file: Path +) -> None: + assert _done(tmp_path, key_file, [review()], [accepted(hour=21)]) is False + + +def test_a_slug_pays_once_ever(tmp_path: Path, key_file: Path) -> None: + earlier = review(day=DAY - timedelta(days=3)) + guard = [accepted(day=DAY - timedelta(days=4))] + assert _done(tmp_path, key_file, [earlier, review()], guard) is False + + +def test_an_unpaid_first_review_still_spends_the_slug( + tmp_path: Path, key_file: Path +) -> None: + earlier = review(day=DAY - timedelta(days=20)) + assert _done(tmp_path, key_file, [review(), earlier], [accepted()]) is False + + +def test_a_review_of_another_day_pays_nothing(tmp_path: Path, key_file: Path) -> None: + row = review(day=DAY - timedelta(days=1)) + assert _done( + tmp_path, key_file, [row], [accepted(day=DAY - timedelta(days=1))] + ) is (False) + + +def test_a_future_stamp_pays_nothing_today(tmp_path: Path, key_file: Path) -> None: + assert _done(tmp_path, key_file, [review(hour=23)], [accepted()]) is False + + +def test_a_bad_stamp_pays_nothing_and_warns( + tmp_path: Path, key_file: Path, caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.WARNING) + row = review(finished_at="soon") + assert _done(tmp_path, key_file, [row], [accepted()]) is False + assert "finished_at" in caplog.text + + +def test_a_missing_slug_pays_nothing_and_warns( + tmp_path: Path, key_file: Path, caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.WARNING) + assert _done(tmp_path, key_file, [review(None)], [accepted()]) is False + assert "title_slug" in caplog.text + + +def test_a_missing_guard_ledger_cannot_check( + tmp_path: Path, key_file: Path, caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.WARNING) + assert _done(tmp_path, key_file, [review()], None) is None + assert len(caplog.records) == 1 + assert "guard" in caplog.text + + +def test_an_unreadable_guard_ledger_cannot_check( + tmp_path: Path, key_file: Path, caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.WARNING) + ledger = home_with(tmp_path, [review()], []) + (tmp_path / GUARD_LEDGER).write_text("{not json", encoding="utf-8") + assert done_today(REVIEW, ledger, key_file, now=evening()) is None + assert len(caplog.records) == 1 + + +def test_no_review_today_never_reads_the_guard(tmp_path: Path, key_file: Path) -> None: + assert _done(tmp_path, key_file, [], None) is False + + +def test_a_missing_review_ledger_is_an_honest_no( + tmp_path: Path, key_file: Path +) -> None: + ledger = tmp_path / str(REVIEW.ledger) + assert done_today(REVIEW, ledger, key_file, now=evening()) is False + + +def test_a_big_amount_still_pays_one_unit(tmp_path: Path, key_file: Path) -> None: + row = {k: v for k, v in review().items() if k != "hmac"} + ledger = home_with(tmp_path, [sign({**row, "amount": 1000})], [accepted()]) + assert credit_units(REVIEW, ledger, key_file, DAY) == 1 diff --git a/earned_time/earned_time/tests/test_review_resolve.py b/earned_time/earned_time/tests/test_review_resolve.py new file mode 100644 index 0000000..6abbc56 --- /dev/null +++ b/earned_time/earned_time/tests/test_review_resolve.py @@ -0,0 +1,123 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The review top-up in the day (0.23.0): added last, capped, never a rung.""" + +from __future__ import annotations + +from datetime import date, timedelta +from typing import TYPE_CHECKING + +from earned_time import ( + REVIEW, + REVIEW_FROM, + REVIEW_SHUTDOWN_MINUTES, + all_earners, + base_for, + earners_for, + maturity, + resolve, + shutdown_ceiling_for, + shutdown_minutes_for, +) +from earned_time.tests._review_rows import DAY, accepted, home_with, review + +if TYPE_CHECKING: + from pathlib import Path + +NOTHING: dict[str, int | bool | None] = { + "workout": 0, + "leetcode": False, + "reading": False, + "tutor": 0, +} +EVERYTHING: dict[str, int | bool | None] = { + "workout": 1, + "leetcode": True, + "reading": True, + "tutor": 60, +} + + +def _day(answers: dict[str, int | bool | None], **kwargs: bool) -> int: + return resolve(answers, DAY, **kwargs).shutdown_minutes + + +def test_the_constants() -> None: + assert REVIEW_SHUTDOWN_MINUTES == 20 + assert date(2026, 11, 23) == REVIEW_FROM + assert REVIEW.gaming_minutes == 0 + assert REVIEW.topup + assert REVIEW.penalty_from is None + assert REVIEW.confirmed_on is None + + +def test_the_review_pays_twenty_flat() -> None: + with_review = _day({**NOTHING, "review": True}) + assert with_review - _day({**NOTHING, "review": False}) == REVIEW_SHUTDOWN_MINUTES + assert shutdown_minutes_for(REVIEW, DAY) == REVIEW_SHUTDOWN_MINUTES + + +def test_two_units_still_pay_twenty() -> None: + assert _day({**NOTHING, "review": 2}) == _day({**NOTHING, "review": 1}) + assert resolve({**NOTHING, "review": 2}, DAY).term("review").shutdown_minutes == 20 + + +def test_it_is_capped_at_the_ceiling() -> None: + near = {**EVERYTHING, "tutor": 50} + assert _day(near) == shutdown_ceiling_for(DAY) - 10 + assert _day({**near, "review": True}) == shutdown_ceiling_for(DAY) + + +def test_it_is_worth_nothing_on_a_full_day() -> None: + full = _day({**EVERYTHING, "review": False}) + assert full == shutdown_ceiling_for(DAY) + assert _day({**EVERYTHING, "review": True}) == full + + +def test_the_floor_does_not_move() -> None: + without = tuple(e for e in earners_for(DAY) if e is not REVIEW) + assert base_for(DAY) == base_for(DAY, without) + assert _day({**NOTHING, "review": False}) == base_for(DAY).shutdown_minutes + assert _day({**NOTHING, "review": None}) == base_for(DAY).shutdown_minutes + + +def test_could_not_check_earns_nothing_but_says_so() -> None: + term = resolve({**NOTHING, "review": None}, DAY).term("review") + assert term.answer is None + assert term.shutdown_minutes == 0 + + +def test_not_registered_before_the_start_date() -> None: + before = REVIEW_FROM - timedelta(days=1) + assert REVIEW not in earners_for(before) + assert REVIEW in earners_for(REVIEW_FROM) + assert resolve({**NOTHING, "review": True}, before).shutdown_minutes == ( + resolve(NOTHING, before).shutdown_minutes + ) + + +def test_every_registry_view_watches_its_ledger() -> None: + assert REVIEW in all_earners() + + +def test_a_sick_day_adds_it_on_top() -> None: + sick = _day({**NOTHING, "review": False}, sick=True) + assert _day({**NOTHING, "review": True}, sick=True) == sick + 20 + + +def test_a_full_sick_day_stays_at_the_ceiling() -> None: + assert _day({**EVERYTHING, "review": True}, sick=True) == shutdown_ceiling_for(DAY) + + +def test_a_sick_day_before_unlimited_gaming_adds_it_too() -> None: + old = date(2026, 11, 1) + registry = (*earners_for(old), REVIEW) + base = resolve({**NOTHING, "review": False}, old, registry, sick=True) + paid = resolve({**NOTHING, "review": True}, old, registry, sick=True) + assert paid.shutdown_minutes == base.shutdown_minutes + 20 + + +def test_maturity_never_penalises_it(tmp_path: Path, key_file: Path) -> None: + ledger = home_with(tmp_path, [review()], [accepted()]) + verdict = maturity(REVIEW, ledger, key_file, DAY) + assert verdict.penalty_start is None + assert any("top-up" in reason for reason in verdict.reasons)