Read progress from the last good row

The day's last verified progress row for the source wins, and both done
and target come from that one row. max(done) with max(target) could pair
a stale target with a new done when a gate re-derives its target within
a day (book-guard does). The rule reads neither created_at nor device,
which the workout ledger does not write.

A later row that fails verification, has the wrong kind, source or day,
or has unreadable numbers is skipped; no good row is still None. The
public API, the version and every other behaviour are unchanged.

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:44:20 +01:00
parent e5e457d8a9
commit 644d372625
6 changed files with 224 additions and 26 deletions

View File

@ -37,9 +37,14 @@ have none and never pay by share).
(no int, float, sign, space, empty string or other script's digits); (no int, float, sign, space, empty string or other script's digits);
- `target` is at least 1. - `target` is at least 1.
`done` is capped at `target`. Over the matching rows the largest `done` and the `done` is capped at `target`. Among the matching rows that verify, the last one
largest `target` win, so a replayed or deleted row can only lower the share in file order wins, and `done` and `target` both come from that one row. A gate
while the target stays the same. can re-derive its target within a day (book-guard does), so mixing rows would
pair a stale target with a new done. The rule reads neither `created_at` nor
`device` (the workout ledger writes neither). A later row that fails any check
above is skipped, so the last good row wins; no good row is `None`. A signed
row copied to the end of the file wins as it is: the key is the trust, not the
position.
`progress_map(day, home, key_file, *, earners=None, gate_off=())` does this for `progress_map(day, home, key_file, *, earners=None, gate_off=())` does this for
every earner of `earners_for(day)` (or the registry given) and returns every earner of `earners_for(day)` (or the registry given) and returns

View File

@ -125,9 +125,9 @@ and the rules are in [DOCS-review.md](DOCS-review.md).
A gate signs "done N of target M for day D" and `resolve(..., progress=)` pays a A gate signs "done N of target M for day D" and `resolve(..., progress=)` pays a
no that share of a yes (`60 * 1 // 3 = 20`), for shutdown, gaming and sick no that share of a yes (`60 * 1 // 3 = 20`), for shutdown, gaming and sick
days. A yes pays full and "could not check" nothing, as ever; with no row days, from the day's last good row. A yes pays full and "could not check"
anywhere every output is 0.23.0's. The row, the reader and every fail-closed nothing, as ever; with no row anywhere every output is 0.23.0's. The row, the
case are in [DOCS-progress.md](DOCS-progress.md). reader and every fail-closed case are in [DOCS-progress.md](DOCS-progress.md).
## Gate maturity (0.6.0) ## Gate maturity (0.6.0)

View File

@ -74,12 +74,12 @@ def read_progress(
) -> Progress | None: ) -> Progress | None:
"""``earner``'s signed progress for ``day``, or ``None``. """``earner``'s signed progress for ``day``, or ``None``.
Over the rows that verify and match, the largest ``done`` and the largest Of the rows that verify and match, the last one in file order wins, and
``target`` (a replay or a lost row can only lower the share, never raise ``done`` and ``target`` both come from it. A later row that fails
it at one target). ``None`` for: no such row, a bad signature, another day verification, is for another kind, source or day, or has unreadable numbers
or source, bad integers, a zero target, an unreadable ledger or key is skipped, so the last good row wins. ``None`` for: no good row, an
(logged), ``gate_off`` (the gate has no price today), or an earner with no unreadable ledger or key (logged), ``gate_off`` (the gate has no price
``progress_source``. today), or an earner with no ``progress_source``.
""" """
source = earner.progress_source source = earner.progress_source
if gate_off or source is None: if gate_off or source is None:
@ -88,14 +88,18 @@ def read_progress(
rows = None if key is None else read_rows(ledger, earner) rows = None if key is None else read_rows(ledger, earner)
if key is None or rows is None: if key is None or rows is None:
return None return None
facts = [ # The last good row in file order wins, as one (done, target) pair: a gate
f # can re-derive its target within a day, so mixing rows would pair a stale
for r in rows # target with a new done. Nothing here reads created_at or device (the
if isinstance(r, dict) and (f := _fact(r, source, day)) and verified(r, key) # workout ledger writes neither).
] for row in reversed(rows):
if not facts: if (
isinstance(row, dict)
and (f := _fact(row, source, day))
and verified(row, key)
):
return f
return None return None
return Progress(max(f.done for f in facts), max(f.target for f in facts))
def progress_map( def progress_map(

View File

@ -63,3 +63,29 @@ def tampered(row: dict[str, object], **detail: object) -> dict[str, object]:
old = row["detail"] old = row["detail"]
assert isinstance(old, dict) assert isinstance(old, dict)
return {**row, "detail": {**old, **detail}} return {**row, "detail": {**old, **detail}}
def bare(
done: object = "1",
target: object = "3",
source: str = "workout",
day: date = DAY,
) -> dict[str, object]:
"""A signed progress row with no ``created_at`` and no ``device``.
The workout ledger writes rows like this; the reader must accept them.
"""
return signed(
{
"kind": "progress",
"entry_id": f"progress:{day.isoformat()}:{done}:{target}",
"day": day.isoformat(),
"amount": 0,
"detail": {
"source": source,
"for_day": day.isoformat(),
"done": done,
"target": target,
},
}
)

View File

@ -0,0 +1,169 @@
# Copyright (c) 2026 Krzysztof Rudnicki
"""Among a day's good progress rows the last in file order wins, as one pair."""
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
import pytest
from earned_time import (
LEETCODE,
READING,
WORKOUT,
Progress,
entry_signature,
read_progress,
)
from earned_time.tests._maturity_rows import signed
from earned_time.tests._progress_rows import (
DAY,
bare,
progress,
tampered,
write,
)
if TYPE_CHECKING:
from collections.abc import Callable
from pathlib import Path
Reader = Callable[..., Progress | None]
@pytest.fixture
def read(tmp_path: Path, key_file: Path) -> Reader:
"""Read LeetCode progress for ``DAY`` out of a ledger holding ``rows``."""
def reader(rows: list[object]) -> Progress | None:
ledger = write(tmp_path / "ledger.json", rows)
return read_progress(LEETCODE, ledger, key_file, DAY)
return reader
def test_a_later_row_with_a_lower_target_wins_whole(read: Reader) -> None:
rows = [progress(done="1", target="5"), progress(done="2", target="3")]
assert read(rows) == Progress(2, 3)
def test_a_later_row_with_a_lower_done_wins_whole(read: Reader) -> None:
rows = [progress(done="2", target="3"), progress(done="1", target="3")]
assert read(rows) == Progress(1, 3)
def test_a_later_row_with_a_higher_pair_wins_whole(read: Reader) -> None:
rows = [progress(done="1", target="3"), progress(done="2", target="4")]
assert read(rows) == Progress(2, 4)
def test_file_order_decides_not_the_numbers(read: Reader) -> None:
rows = [progress(done="1", target="3"), progress(done="2", target="4")]
assert read(rows[::-1]) == Progress(1, 3)
def test_the_last_row_of_three_wins(read: Reader) -> None:
rows = [
progress(done="3", target="3"),
progress(done="1", target="6"),
progress(done="2", target="6"),
]
assert read(rows) == Progress(2, 6)
def test_a_trailing_forged_row_is_skipped(read: Reader) -> None:
forged = tampered(progress(done="3", target="3"), done="2")
assert read([progress(done="1", target="3"), forged]) == Progress(1, 3)
def test_a_trailing_row_with_the_wrong_key_is_skipped(read: Reader) -> None:
row = progress(done="3", target="3")
row["hmac"] = entry_signature(row, b"someone else")
assert read([progress(done="1", target="3"), row]) == Progress(1, 3)
def test_a_trailing_unsigned_row_is_skipped(read: Reader) -> None:
row = progress(done="3", target="3")
del row["hmac"]
assert read([progress(done="1", target="3"), row]) == Progress(1, 3)
@pytest.mark.parametrize("junk", ["garbage", 7, None, [], ["x"], {}, {"kind": 1}])
def test_a_trailing_garbage_entry_is_skipped(read: Reader, junk: object) -> None:
assert read([progress(done="1", target="3"), junk]) == Progress(1, 3)
@pytest.mark.parametrize(
"bad", [("x", "3"), ("1", "x"), ("1", "0"), ("", "3"), ("1", "9" * 5000)]
)
def test_a_trailing_unparsable_row_is_skipped(
read: Reader, bad: tuple[str, str]
) -> None:
rows = [progress(done="1", target="3"), progress(done=bad[0], target=bad[1])]
assert read(rows) == Progress(1, 3)
def test_a_trailing_credit_row_is_skipped(read: Reader) -> None:
credit = signed({**progress(done="3", target="3"), "kind": "credit"})
assert read([progress(done="1", target="3"), credit]) == Progress(1, 3)
def test_trailing_rows_of_another_day_or_source_are_skipped(read: Reader) -> None:
rows = [
progress(done="1", target="3"),
progress(done="3", target="3", day=DAY - timedelta(days=1)),
progress(done="3", target="3", day=DAY + timedelta(days=1)),
progress(done="3", target="3", source="reading"),
progress(done="3", target="3", source="workout"),
]
assert read(rows) == Progress(1, 3)
def test_a_malformed_detail_row_is_skipped(read: Reader) -> None:
rows = [progress(done="1", target="3"), {**progress(), "detail": "x"}]
assert read(rows) == Progress(1, 3)
def test_only_bad_rows_read_as_none(read: Reader) -> None:
rows = [progress(done="x"), progress(source="reading"), "garbage"]
assert read(rows) is None
def test_rows_without_created_at_and_device_are_accepted(
tmp_path: Path, key_file: Path
) -> None:
first, last = bare(done="1", target="3"), bare(done="2", target="3")
assert "created_at" not in last
assert "device" not in last
ledger = write(tmp_path / "w.json", [first, last])
assert read_progress(WORKOUT, ledger, key_file, DAY) == Progress(2, 3)
def test_the_rule_does_not_read_created_at(read: Reader) -> None:
early = signed(
{**bare(done="2", source="leetcode"), "created_at": "2026-11-24T23:00:00+00:00"}
)
late = signed(
{**bare(done="1", source="leetcode"), "created_at": "2026-11-24T01:00:00+00:00"}
)
# File order, not timestamps: the later row in the file wins.
assert read([early, late]) == Progress(1, 3)
assert read([late, early]) == Progress(2, 3)
def test_each_source_reads_its_own_last_row(tmp_path: Path, key_file: Path) -> None:
rows = [
bare(done="1", target="3", source="workout"),
progress(done="2", target="4", source="reading"),
bare(done="3", target="3", source="workout"),
progress(done="1", target="9", source="reading"),
]
ledger = write(tmp_path / "mixed.json", rows)
assert read_progress(WORKOUT, ledger, key_file, DAY) == Progress(3, 3)
assert read_progress(READING, ledger, key_file, DAY) == Progress(1, 9)
def test_the_last_good_row_is_still_capped_at_its_target(read: Reader) -> None:
rows = [progress(done="1", target="3"), progress(done="9", target="4")]
assert read(rows) == Progress(4, 4)

View File

@ -119,12 +119,6 @@ def test_zero_done_is_a_valid_zero(read: Reader) -> None:
assert read([progress(done="0", target="3")]) == Progress(0, 3) assert read([progress(done="0", target="3")]) == Progress(0, 3)
def test_the_max_done_and_the_max_target_win(read: Reader) -> None:
rows = [progress(done="1", target="3"), progress(done="2", target="4")]
assert read(rows) == Progress(2, 4)
assert read(rows[::-1]) == Progress(2, 4)
def test_a_bad_row_beside_a_good_one_is_ignored(read: Reader) -> None: def test_a_bad_row_beside_a_good_one_is_ignored(read: Reader) -> None:
rows = [progress(done="x", target="3"), progress(done="2", target="3")] rows = [progress(done="x", target="3"), progress(done="2", target="3")]
assert read(rows) == Progress(2, 3) assert read(rows) == Progress(2, 3)