earned_time: 0.23.0, document the review top-up
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
leetcode-coach pre-commit / pre-commit (push) Waiting to run
leetcode-coach tests / test (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

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4
This commit is contained in:
Krzysztof Rudnicki 2026-11-21 22:02:01 +01:00
parent b25933f975
commit b0ca506397
3 changed files with 62 additions and 2 deletions

View File

@ -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:<slug>", "kind": "credit", "day": "<YYYY-MM-DD>",
"created_at": "<iso>", "amount": 1, "device": "pc",
"detail": {"title_slug": "<slug>", "cause": "<id>",
"source": "leetcode-coach-review", "finished_at": "<unix seconds>"},
"hmac": "<entry_signature>"}
```
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.

View File

@ -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 pay from the switch (gaming pay before it), capped at the ceiling. The two
are equal on the unified ladder, so no number moves. 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) ## Gate maturity (0.6.0)
How far to trust a gate, computed from its ledger by `maturity()`, is in 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 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. the day-aware sum. Never read `earner.shutdown_minutes`: pre-ladder value.
- `day_window(day)`, `today_window(now=None)`, `entry_signature`, `verified`. - `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 ## The workout ledger
@ -232,7 +242,7 @@ Unbacked timer time pays 0 from 2026-11-08 (focus_project 0.10.0).
## Install ## Install
```console ```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 The root `steam-backlog-enforcer.service` sets `HOME=/home/kuhy` and imports from

View File

@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project] [project]
name = "earned-time" 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" description = "Penalty-then-reward registry: what every gate app earns in gaming time and shutdown time"
requires-python = ">=3.14" requires-python = ">=3.14"
dependencies = [] dependencies = []