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
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

View File

@ -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 = []