Export term_for: one derivation of a term
Some checks are pending
earned_time pre-commit / pre-commit (push) Waiting to run
earned_time tests / test (push) Waiting to run
file length / file-length (push) Waiting to run
gatelock tests / test (push) Waiting to run
kuhy_credit drift / drift (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run

term_for(earner, day, *, answer, progress=None) returns the Term an
earner pays: the ladder rung, the share of a row, the full-pay cap and
the review's dated rule. resolve builds every term through it, so a
consumer pricing one earner cannot disagree with resolve and never
re-derives a share.

A grid test pins term_for == resolve's term for every earner, answer,
row and day either side of REVIEW_PROGRESS_FROM, and a second test
checks the minutes against the written rules, not the library code.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZLyjnLjB1THD6ckou
This commit is contained in:
Krzysztof Rudnicki 2026-11-22 18:55:54 +01:00
parent 77827e9abb
commit c06f2daa9a
6 changed files with 226 additions and 38 deletions

View File

@ -103,6 +103,25 @@ earners:
Before `REVIEW_PROGRESS_FROM` the review pays as in 0.23.0 (a yes pays 20, a no Before `REVIEW_PROGRESS_FROM` the review pays as in 0.23.0 (a yes pays 20, a no
0) and ignores every progress row. 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 ## Not credits
A `progress` row has `amount` 0 and its own kind. `done_today`, `credit_units`, A `progress` row has `amount` 0 and its own kind. `done_today`, `credit_units`,

View File

@ -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 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 [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. 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) ## 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=()) -> - `progress_map(day, home, key_file, *, earners=None, gate_off=()) ->
dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *, dict[str, Progress]`, `read_progress(earner, ledger, key_file, day, *,
gate_off=False) -> Progress | None`, `Progress(done, target)`, 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 ## The workout ledger

View File

@ -122,6 +122,7 @@ from earned_time._review import (
paid_reviews, paid_reviews,
review_match, review_match,
) )
from earned_time._share import term_for
from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from from earned_time._sick import SICK_SHUTDOWN_FLOOR_MINUTES, sick_shutdown_from
__all__ = [ __all__ = [
@ -204,6 +205,7 @@ __all__ = [
"shutdown_ceiling_for", "shutdown_ceiling_for",
"shutdown_minutes_for", "shutdown_minutes_for",
"sick_shutdown_from", "sick_shutdown_from",
"term_for",
"today_window", "today_window",
"tutor_quota_for", "tutor_quota_for",
"verified", "verified",

View File

@ -27,12 +27,11 @@ from typing import TYPE_CHECKING, Final
from earned_time._floor import gaming_cut, is_penalised, shutdown_floor from earned_time._floor import gaming_cut, is_penalised, shutdown_floor
from earned_time._gaming import gaming_enforced 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._leisure import base_minutes, ceiling_minutes, is_leisure
from earned_time._registry import all_earners, earners_for from earned_time._registry import all_earners, earners_for
from earned_time._resolution import Base, Resolution, Term from earned_time._resolution import Base, Resolution, Term
from earned_time._review import ReviewEarner from earned_time._share import term_for
from earned_time._share import review_term, share_term
from earned_time._sick import sick_or from earned_time._sick import sick_or
if TYPE_CHECKING: 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( def _check_registered(
answers: Mapping[str, Answer], registry: tuple[Earner, ...] answers: Mapping[str, Answer], registry: tuple[Earner, ...]
) -> None: ) -> None:
@ -113,31 +106,17 @@ def _term(
) -> Term: ) -> Term:
"""``item``'s term on ``day``; no answer at all is logged and earns nothing. """``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 The pay itself is :func:`~earned_time.term_for`, shared with every consumer.
``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).
""" """
if item.name not in answers: if item.name not in answers:
_logger.warning( _logger.warning(
"No answer for the %s earner; it earns nothing today", item.label "No answer for the %s earner; it earns nothing today", item.label
) )
units = _units(answers.get(item.name)) return term_for(
if isinstance(item, ReviewEarner): item,
if day >= REVIEW_PROGRESS_FROM: day,
return review_term(item, units, day, progress) answer=answers.get(item.name),
progress = None progress=(progress or {}).get(item.name),
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),
) )

View File

@ -11,11 +11,11 @@ from __future__ import annotations
import logging import logging
from typing import TYPE_CHECKING, Final 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._resolution import Term
from earned_time._review import ReviewEarner
if TYPE_CHECKING: if TYPE_CHECKING:
from collections.abc import Mapping
from datetime import date from datetime import date
from earned_time._policy import Earner 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( def _review_term(
item: Earner, item: Earner, units: int | None, day: date, progress: Progress | None
units: int | None,
day: date,
progress: Mapping[str, Progress] | None,
) -> Term: ) -> Term:
"""The review's term from ``REVIEW_PROGRESS_FROM``: a credited review needs a row. """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 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. 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: if units and share is None:
_logger.warning( _logger.warning(
"%s credited with no progress row on %s; it pays nothing", "%s credited with no progress row on %s; it pays nothing",
@ -85,3 +82,49 @@ def review_term(
if share is None: if share is None:
return Term(item, units, 0, 0) return Term(item, units, 0, 0)
return share_term(item, units, day, share) 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),
)

View File

@ -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,
)