mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-21 22:12:27 +01:00
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
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:
parent
b25933f975
commit
b0ca506397
50
earned_time/DOCS-review.md
Normal file
50
earned_time/DOCS-review.md
Normal 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.
|
||||
@ -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
|
||||
|
||||
@ -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 = []
|
||||
|
||||
Loading…
Reference in New Issue
Block a user