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);
- `target` is at least 1.
`done` is capped at `target`. Over the matching rows the largest `done` and the
largest `target` win, so a replayed or deleted row can only lower the share
while the target stays the same.
`done` is capped at `target`. Among the matching rows that verify, the last one
in file order wins, and `done` and `target` both come from that one row. A gate
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
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
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
anywhere every output is 0.23.0's. The row, the reader and every fail-closed
case are in [DOCS-progress.md](DOCS-progress.md).
days, from the day's last good row. A yes pays full and "could not check"
nothing, as ever; with no row anywhere every output is 0.23.0's. The row, the
reader and every fail-closed case are in [DOCS-progress.md](DOCS-progress.md).
## Gate maturity (0.6.0)

View File

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

View File

@ -63,3 +63,29 @@ def tampered(row: dict[str, object], **detail: object) -> dict[str, object]:
old = row["detail"]
assert isinstance(old, dict)
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)
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:
rows = [progress(done="x", target="3"), progress(done="2", target="3")]
assert read(rows) == Progress(2, 3)