diff --git a/earned_time/DOCS-progress.md b/earned_time/DOCS-progress.md index 9cfe7d8..6754688 100644 --- a/earned_time/DOCS-progress.md +++ b/earned_time/DOCS-progress.md @@ -103,6 +103,25 @@ earners: Before `REVIEW_PROGRESS_FROM` the review pays as in 0.23.0 (a yes pays 20, a no 0) and ignores every progress row. +## One derivation: `term_for` + +`term_for(earner, day, *, answer, progress=None) -> Term` is the only place an +earner's pay for a day is derived, and `resolve` builds every one of its terms +through it. A consumer that prices one earner (the screen-locker's live pass) +reads the row with `read_progress` and calls it; it reads `shutdown_minutes` +and `gaming_minutes` off the `Term`. **Consumers never re-derive a share**: the +review's dated rule, the ladder rung, the floor and the cap at full all live +here, and a local `full * done // target` goes stale the day a rule changes. + +```python +fact = earned_time.read_progress(earner, ledger, key_file, day, gate_off=off) +pay = earned_time.term_for(earner, day, answer=answer, progress=fact).shutdown_minutes +``` + +`answer` is the unit count (`True`/`False` are 1/0) or `None`; `progress` is the +verified row or `None`. A test pins that the two always agree for every earner, +answer, row and day either side of `REVIEW_PROGRESS_FROM`. + ## Not credits A `progress` row has `amount` 0 and its own kind. `done_today`, `credit_units`, diff --git a/earned_time/README.md b/earned_time/README.md index 797d66d..fd91bca 100644 --- a/earned_time/README.md +++ b/earned_time/README.md @@ -130,6 +130,8 @@ nothing, as ever; with no row anywhere every output is 0.23.0's, the review excepted. The row, the reader and every fail-closed case are in [DOCS-progress.md](DOCS-progress.md). The review differs from `REVIEW_PROGRESS_FROM` (2026-11-24): a credited review pays only by its row (`20 * done // target`), and with no verified row pays 0. +One earner's pay for a day is `term_for(earner, day, *, answer, progress=None)`, +the code `resolve` itself uses: consumers never re-derive a share. ## Gate maturity (0.6.0) @@ -168,7 +170,8 @@ How far to trust a gate, computed from its ledger by `maturity()`, is in - `progress_map(day, home, key_file, *, earners=None, gate_off=()) -> dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *, gate_off=False) -> Progress | None`, `Progress(done, target)`, - `Earner.progress_source`, `Term.progress`, `REVIEW_PROGRESS_FROM` (0.24.0). + `Earner.progress_source`, `Term.progress`, `REVIEW_PROGRESS_FROM`, + `term_for(earner, day, *, answer, progress=None) -> Term` (0.24.0). ## The workout ledger diff --git a/earned_time/earned_time/__init__.py b/earned_time/earned_time/__init__.py index 800e8b7..36807aa 100644 --- a/earned_time/earned_time/__init__.py +++ b/earned_time/earned_time/__init__.py @@ -122,6 +122,7 @@ from earned_time._review import ( paid_reviews, review_match, ) +from earned_time._share import term_for from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from __all__ = [ @@ -204,6 +205,7 @@ __all__ = [ "shutdown_ceiling_for", "shutdown_minutes_for", "sick_shutdown_from", + "term_for", "today_window", "tutor_quota_for", "verified", diff --git a/earned_time/earned_time/_resolve.py b/earned_time/earned_time/_resolve.py index 77bfe2f..b53c5ac 100644 --- a/earned_time/earned_time/_resolve.py +++ b/earned_time/earned_time/_resolve.py @@ -27,12 +27,11 @@ from typing import TYPE_CHECKING, Final from earned_time._floor import gaming_cut, is_penalised, shutdown_floor from earned_time._gaming import gaming_enforced -from earned_time._ladder import REVIEW_PROGRESS_FROM, shutdown_ceiling_for +from earned_time._ladder import shutdown_ceiling_for from earned_time._leisure import base_minutes, ceiling_minutes, is_leisure from earned_time._registry import all_earners, earners_for from earned_time._resolution import Base, Resolution, Term -from earned_time._review import ReviewEarner -from earned_time._share import review_term, share_term +from earned_time._share import term_for from earned_time._sick import sick_or if TYPE_CHECKING: @@ -88,12 +87,6 @@ def _base( ) -def _units(answer: Answer) -> int | None: - if answer is None: - return None - return max(0, int(answer)) - - def _check_registered( answers: Mapping[str, Answer], registry: tuple[Earner, ...] ) -> None: @@ -113,31 +106,17 @@ def _term( ) -> Term: """``item``'s term on ``day``; no answer at all is logged and earns nothing. - Progress pays only a no (``0``/``False``): a yes pays in full as ever and - ``None`` ("could not check") earns nothing, row or no row. The review is - the exception (:func:`~earned_time._share.review_term`): from - ``REVIEW_PROGRESS_FROM`` only a yes pays, and only by its row; before it - progress is ignored (0.23.0). + The pay itself is :func:`~earned_time.term_for`, shared with every consumer. """ if item.name not in answers: _logger.warning( "No answer for the %s earner; it earns nothing today", item.label ) - units = _units(answers.get(item.name)) - if isinstance(item, ReviewEarner): - if day >= REVIEW_PROGRESS_FROM: - return review_term(item, units, day, progress) - progress = None - no = units is not None and units < 1 - share = (progress or {}).get(item.name) if no else None - if share is not None: - return share_term(item, units, day, share) - count = units or 0 - return Term( - earner=item, - answer=units, - gaming_minutes=item.gaming_for(count), - shutdown_minutes=item.shutdown_for(count, day), + return term_for( + item, + day, + answer=answers.get(item.name), + progress=(progress or {}).get(item.name), ) diff --git a/earned_time/earned_time/_share.py b/earned_time/earned_time/_share.py index 1a81466..68ba3b6 100644 --- a/earned_time/earned_time/_share.py +++ b/earned_time/earned_time/_share.py @@ -11,11 +11,11 @@ from __future__ import annotations import logging from typing import TYPE_CHECKING, Final -from earned_time._ladder import shutdown_minutes_for +from earned_time._ladder import REVIEW_PROGRESS_FROM, shutdown_minutes_for from earned_time._resolution import Term +from earned_time._review import ReviewEarner if TYPE_CHECKING: - from collections.abc import Mapping from datetime import date from earned_time._policy import Earner @@ -61,11 +61,8 @@ def share_term(item: Earner, units: int | None, day: date, share: Progress) -> T ) -def review_term( - item: Earner, - units: int | None, - day: date, - progress: Mapping[str, Progress] | None, +def _review_term( + item: Earner, units: int | None, day: date, progress: Progress | None ) -> Term: """The review's term from ``REVIEW_PROGRESS_FROM``: a credited review needs a row. @@ -75,7 +72,7 @@ def review_term( logged). A no and ``None`` pay 0 whatever a row says, since the guard's accepted submission, not the row, is the evidence a review happened. """ - share = (progress or {}).get(item.name) if units else None + share = progress if units else None if units and share is None: _logger.warning( "%s credited with no progress row on %s; it pays nothing", @@ -85,3 +82,49 @@ def review_term( if share is None: return Term(item, units, 0, 0) return share_term(item, units, day, share) + + +def term_for( + earner: Earner, + day: date, + *, + answer: int | bool | None, + progress: Progress | None = None, +) -> Term: + """What ``earner`` pays on ``day``: the one derivation, for every consumer. + + :func:`~earned_time.resolve` builds each of its terms here, so a consumer + pricing one earner (the screen-locker's live pass) cannot disagree with it: + consumers never re-derive a share. Read ``shutdown_minutes`` and + ``gaming_minutes`` off the result; ``Term.progress`` is the row it was + paid from. + + Args: + earner: The earner (its ladder rung on ``day`` is the full pay). + day: The day priced. + answer: The consumer's answer: a unit count (``True``/``False`` are + 1/0), or ``None`` for "could not check", which earns nothing. + progress: The earner's verified signed row for ``day`` + (:func:`~earned_time.read_progress`), or ``None`` for no row. + + Returns: + The term. A yes pays full as ever. A no pays ``full * done // target`` + of ``progress``, floored, never above full, and nothing without a row. + The review is the exception: from ``REVIEW_PROGRESS_FROM`` only a yes + pays, only by its row, and a yes with no row pays 0; before it the row + is ignored (0.23.0). + """ + units = None if answer is None else max(0, int(answer)) + if isinstance(earner, ReviewEarner): + if day >= REVIEW_PROGRESS_FROM: + return _review_term(earner, units, day, progress) + progress = None + if progress is not None and units is not None and units < 1: + return share_term(earner, units, day, progress) + count = units or 0 + return Term( + earner=earner, + answer=units, + gaming_minutes=earner.gaming_for(count), + shutdown_minutes=earner.shutdown_for(count, day), + ) diff --git a/earned_time/earned_time/tests/test_term_for.py b/earned_time/earned_time/tests/test_term_for.py new file mode 100644 index 0000000..181ce90 --- /dev/null +++ b/earned_time/earned_time/tests/test_term_for.py @@ -0,0 +1,142 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""``term_for``: the one place an earner's pay for a day is derived. + +``resolve`` builds its terms through it, so a consumer pricing one earner (the +screen-locker's live pass) can never disagree with ``resolve``. +""" + +from __future__ import annotations + +from datetime import date +from itertools import product +from typing import Any + +import pytest + +from earned_time import ( + LEETCODE, + REVIEW, + REVIEW_PROGRESS_FROM, + WORKOUT, + Earner, + Progress, + Term, + earners_for, + resolve, + shutdown_minutes_for, + term_for, +) + +DAYS = ( + date(2026, 10, 5), + date(2026, 10, 16), + date(2026, 11, 22), + REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day - 1), + REVIEW_PROGRESS_FROM, + REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day + 1), + date(2027, 1, 1), +) +ANSWERS: tuple[int | bool | None, ...] = (True, False, None, 0, 1, 2) +FACTS: tuple[Progress | None, ...] = ( + None, + Progress(0, 3), + Progress(1, 3), + Progress(2, 3), + Progress(3, 3), + Progress(1, 1), + Progress(7, 2), +) +LADDER = date(2026, 11, 22) + + +def test_the_signature_is_keyword_clear() -> None: + loose: Any = term_for + with pytest.raises(TypeError): + loose(LEETCODE, LADDER, 1) + + +@pytest.mark.parametrize("day", DAYS) +def test_term_for_equals_the_term_resolve_builds(day: date) -> None: + for item, answer, fact in product(earners_for(day), ANSWERS, FACTS): + others = {e.name: 0 for e in earners_for(day)} + asked = resolve( + {**others, item.name: answer}, + day, + progress=None if fact is None else {item.name: fact}, + ).term(item.name) + got = term_for(item, day, answer=answer, progress=fact) + assert got == asked, (item.name, day, answer, fact) + assert isinstance(got, Term) + + +def test_a_generic_earner_pays_a_share_of_the_ladder_rung() -> None: + full = shutdown_minutes_for(LEETCODE, LADDER) + assert full == 60 + row = Progress(1, 3) + assert term_for(LEETCODE, LADDER, answer=False, progress=row).shutdown_minutes == 20 + assert term_for(LEETCODE, LADDER, answer=False, progress=row).gaming_minutes == 20 + assert term_for(LEETCODE, LADDER, answer=False).shutdown_minutes == 0 + + +def test_a_yes_pays_full_whatever_the_row_says() -> None: + low = term_for(LEETCODE, LADDER, answer=True, progress=Progress(1, 3)) + assert low.shutdown_minutes == shutdown_minutes_for(LEETCODE, LADDER) + assert low.progress is None + + +def test_a_row_never_pays_above_full() -> None: + term = term_for(LEETCODE, LADDER, answer=False, progress=Progress(9, 3)) + assert term.shutdown_minutes == shutdown_minutes_for(LEETCODE, LADDER) + + +def test_none_earns_nothing_even_with_a_full_row() -> None: + assert term_for(LEETCODE, LADDER, answer=None, progress=Progress(3, 3)) == Term( + LEETCODE, None, 0, 0 + ) + + +def test_the_review_follows_its_dated_rule() -> None: + row = Progress(1, 3) + before = REVIEW_PROGRESS_FROM.replace(day=REVIEW_PROGRESS_FROM.day - 1) + assert term_for(REVIEW, before, answer=True, progress=row).shutdown_minutes == 20 + assert term_for(REVIEW, before, answer=False, progress=row).shutdown_minutes == 0 + on = REVIEW_PROGRESS_FROM + assert term_for(REVIEW, on, answer=True, progress=row).shutdown_minutes == 6 + assert term_for(REVIEW, on, answer=True).shutdown_minutes == 0 + assert term_for(REVIEW, on, answer=False, progress=row).shutdown_minutes == 0 + + +def test_a_counted_earner_pays_per_unit() -> None: + day = LADDER + one = term_for(WORKOUT, day, answer=1).shutdown_minutes + assert term_for(WORKOUT, day, answer=True).shutdown_minutes == one + assert term_for(WORKOUT, day, answer=0).shutdown_minutes == 0 + + +def _expected( + item: Earner, day: date, answer: int | None, fact: Progress | None +) -> int: + """The shutdown minutes by the written rules, not by the library's code.""" + if answer is None: + return 0 + full = shutdown_minutes_for(item, day) + yes = answer is True or answer >= 1 + if item is REVIEW and day >= REVIEW_PROGRESS_FROM: + if not yes or fact is None: + return 0 + return full * min(fact.done, fact.target) // fact.target + if yes or (item is REVIEW) or fact is None: + return item.shutdown_for(max(0, int(answer)), day) + return full * min(fact.done, fact.target) // fact.target + + +@pytest.mark.parametrize("day", DAYS) +def test_the_minutes_follow_the_written_rules(day: date) -> None: + for item, answer, fact in product(earners_for(day), ANSWERS, FACTS): + got = term_for(item, day, answer=answer, progress=fact) + assert got.shutdown_minutes == _expected(item, day, answer, fact), ( + item.name, + day, + answer, + fact, + )