From b0ca506397a30c64ea30ab832881480fd3dc8791 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 21 Nov 2026 22:02:01 +0100 Subject: [PATCH] earned_time: 0.23.0, document the review top-up DOCS-review.md holds the coach row contract, the five pay rules, the start date 2026-11-23 and every fail-closed path; README points at it and lists the new API. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4 --- earned_time/DOCS-review.md | 50 ++++++++++++++++++++++++++++++++++++++ earned_time/README.md | 12 ++++++++- earned_time/pyproject.toml | 2 +- 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 earned_time/DOCS-review.md diff --git a/earned_time/DOCS-review.md b/earned_time/DOCS-review.md new file mode 100644 index 0000000..4835dd2 --- /dev/null +++ b/earned_time/DOCS-review.md @@ -0,0 +1,50 @@ +# The LeetCode review top-up (0.23.0) + +kuhy's decision, 2026-11-21 (Q12-Q14): a finished coach review +(`/leetcode review`) pays `REVIEW_SHUTDOWN_MINUTES` (20) shutdown minutes, for +the first paid review of the day only, and 0 gaming minutes. `REVIEW` is in the +registry from `REVIEW_FROM` (2026-11-23, the day after the planned deploy); +`confirmed_on` stays unset until kuhy has seen a real review credited. + +**A top-up, not a rung.** `Earner.topup` is `True` for it: it is not on the +ladder, it does not lower the floor, and it has no penalty (maturity lists it as +"a top-up: nothing to cut, never penalised"). `resolve` adds its 20 to the +day's shutdown and caps the sum at the ceiling, so a day where everything else +is done gains nothing. On a sick day it is added to the sick shutdown, under +the same cap. Its `kind` stays `"flat"` on purpose: consumers that filter +`kind == "flat"` (screen-locker's live pass and reset stamps) pay it with only +a pin bump. A new `kind` literal would have dropped it from that path. + +**The row** (the coach's own ledger, `REVIEW_LEDGER` = +`~/.local/share/leetcode-coach/review_ledger.json`, `{"version": N, "entries": [...]}`), +signed with `entry_signature` and the same shared key as every other ledger: + +```json +{"entry_id": "review:", "kind": "credit", "day": "", + "created_at": "", "amount": 1, "device": "pc", + "detail": {"title_slug": "", "cause": "", + "source": "leetcode-coach-review", "finished_at": ""}, + "hmac": ""} +``` + +A row pays (`paid_reviews`, through `done_today`/`credit_units`) only if all hold: + +- its signature verifies and `detail.source == REVIEW_SOURCE`; +- `finished_at` falls in the day's window (`day` is the fallback, as for + `leetcode_match`, but a row without a usable `finished_at` still pays + nothing, because the lookback needs the time); +- it is the earliest signed review row for its `title_slug`: each slug pays once + ever, and a later row for the same slug, on any day, pays nothing; +- the guard ledger (`GUARD_LEDGER`, the `LEETCODE` ledger) holds a signed, + non-manual `credit` row with `detail.source == "leetcode"`, the same + `title_slug`, and `submitted_at` within `ACCEPTED_LOOKBACK_DAYS` (14) before + `finished_at`. Manual means a `manual`/`manual_grant` source, a `manual:`/`manual_grant:` + id, or a `detail.manual_grant` note. + +The guard ledger is found under the same home as the review ledger +(`guard_ledger_for`): pass `home / REVIEW.ledger`. Failure paths, all closed: +no review row in the window is `False` (the guard ledger is never read); a +missing or unreadable guard ledger, or a review ledger that is not at +`home / REVIEW.ledger`, is `None` with one warning; a row with no slug or a bad +stamp pays nothing, with a warning. `None` earns nothing, like every "could not +check". The amount is ignored: one row is one unit, and the day pays 20 at most. diff --git a/earned_time/README.md b/earned_time/README.md index 843d4dc..f4f0f70 100644 --- a/earned_time/README.md +++ b/earned_time/README.md @@ -139,6 +139,12 @@ budget must read the switch and lift its limit on `False`. pay from the switch (gaming pay before it), capped at the ceiling. The two are equal on the unified ladder, so no number moves. +## The LeetCode review top-up (0.23.0) + +From 2026-11-23 a finished, backed coach review adds 20 shutdown minutes once a +day, capped at the ceiling; never a rung, never in the floor. The row contract +and the rules are in [DOCS-review.md](DOCS-review.md). + ## Gate maturity (0.6.0) How far to trust a gate, computed from its ledger by `maturity()`, is in @@ -169,6 +175,10 @@ How far to trust a gate, computed from its ledger by `maturity()`, is in view lists as still left to earn. `Earner.shutdown_for(units, day=None)` is the day-aware sum. Never read `earner.shutdown_minutes`: pre-ladder value. - `day_window(day)`, `today_window(now=None)`, `entry_signature`, `verified`. +- `REVIEW`, `REVIEW_FROM`, `REVIEW_SHUTDOWN_MINUTES`, `REVIEW_LEDGER`, + `REVIEW_SOURCE`, `GUARD_LEDGER`, `ACCEPTED_LOOKBACK_DAYS`, `review_match`, + `paid_reviews`, `guard_ledger_for(ledger, earner) -> Path | None`; + `Earner.topup` and `Earner.evidence` (0.23.0). ## The workout ledger @@ -232,7 +242,7 @@ Unbacked timer time pays 0 from 2026-11-08 (focus_project 0.10.0). ## Install ```console -pip install --user --break-system-packages --no-deps "earned-time @ git+https://github.com/kuhyx/utils@earned-time-v0.22.0#subdirectory=earned_time" +pip install --user --break-system-packages --no-deps "earned-time @ git+https://github.com/kuhyx/utils@earned-time-v0.23.0#subdirectory=earned_time" ``` The root `steam-backlog-enforcer.service` sets `HOME=/home/kuhy` and imports from diff --git a/earned_time/pyproject.toml b/earned_time/pyproject.toml index 2570e4b..b580714 100644 --- a/earned_time/pyproject.toml +++ b/earned_time/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "earned-time" -version = "0.22.0" +version = "0.23.0" description = "Penalty-then-reward registry: what every gate app earns in gaming time and shutdown time" requires-python = ">=3.14" dependencies = []