From REVIEW_PROGRESS_FROM a credited review pays bonus * done // target of its signed progress row, never more than 20, and with no verified row pays 0 (logged); a row that fails verification is no row. A no or unknown pays 0 whatever a row says, since the guard's accepted submission is the evidence. Before that date the review pays as in 0.23.0 and ignores progress. Other earners are unchanged. The 0.23.0 golden grid asks the review only no or unknown from the switch, since a credited review without a row now differs by design. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxdWZLyjnLjB1THD6ckou |
||
|---|---|---|
| .. | ||
| earned_time | ||
| scripts | ||
| .pre-commit-config.yaml | ||
| DOCS-maturity.md | ||
| DOCS-progress.md | ||
| DOCS-review.md | ||
| DOCS-tutor.md | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
earned_time
Penalty-then-reward for gate apps: one table of what every gate earns in gaming time and shutdown time, read by both consumers.
| consumer | applies | via |
|---|---|---|
| steam-backlog-enforcer | Resolution.gaming_minutes |
_budget_resolve.resolve_budget |
| screen-locker | Resolution.shutdown_minutes |
_shutdown_base.reset_to_base_if_new_day + live pass |
A gate (leetcode-guard, book-guard, anki-guard, screen-locker's workout
credit, ...) never touches either. It publishes a fact — HMAC-signed credit
rows in its ledger — and is registered here once. LeetCode also counts its signed source == "leetcode" charge for the day (0.17.0, ROW_KINDS): a day paid ahead from banked credits earns like a solve; escape and outage charges never do. Since 0.18.0 that charge is the only LeetCode row that earns while the gate is on: a credit is one unit of a price that may be 5, so one solve on a 5-credit day earns nothing. A consumer passes gate_off=True (live: a free day, or a sick day not keeping leetcode) to done_today / first_credit_at / credit_units, and then one verified solve earns again (PAID_DAY_KINDS).
The model
Gaming: a base (gaming_base_minutes_for(day)) minus every earner's
gaming_minutes from its penalty_from date; each earner done adds its
gaming_minutes back. Capped at gaming_ceiling_minutes_for(day).
Leisure budget (0.14.0, _leisure.py). From the first leisure day the
budget covers all leisure (games, browsing, video, messaging): base 5 h -> 7 h,
cap 8 h -> 10 h; pay, penalties and shutdown untouched (full day 480 -> 600).
resolve/base_for(..., leisure=) (0.16.0): None = by the switch file on
day, True = leisure pricing (shadow budget), False = old pricing; a
consumer billing on the 06:00 gaming day passes leisure_active(gaming_day).
The switch file (0.15.0). The first leisure day is leisure_from(): the
YYYY-MM-DD line in /etc/leisure-watch/leisure_from (LEISURE_FROM_PATH,
root:root 0644; read afresh, once per resolve, O_NOFOLLOW|O_NONBLOCK,
regular, <= 64 bytes, strict), else the parked LEISURE_FROM (2027-01-01);
never raises. Consumers ask only leisure_active(day) (gaming day); none
reads the file. leisure-watch go-live writes tomorrow's date; --undo removes it.
Shutdown has two regimes, switched by date (LADDER_FROM, 2026-10-10 —
never a same-day cut):
-
Before
LADDER_FROM: base 20:00 minus the penalties in force, plus each earner'sshutdown_minutes(a second workout +60), capped at 23:00. -
From
LADDER_FROM— the sleep ladder. The ceiling is eight hours of sleep before the alarm:WAKE_MINUTES(07:00) − 8 h = 23:00. The floor is that ceiling minus the sum of every registered earner's rung (aRungper earner name; all of a counted earner's capped units), so doing everything lands exactly on the ceiling. Since 0.6.1TUTOR_FROM == LADDER_FROM, so every real ladder day usesTUTOR_LADDER(below);LADDER, the pre-tutor split (floor 19:00), is never in force on a real day.A second workout earns nothing more (
Rung.extradefaults to 0). Move the alarm (WAKE_MINUTES = 6 * 60) and the whole ladder shifts an hour earlier on its own. Days beforeLADDER_FROMkeep their frozen 23:00 ceiling, so the change never rewrites history.
The two floors are derived separately (_resolve._shutdown_floor), so the
ladder cannot move a gaming minute.
Unified ladder (0.12.0; UNIFIED_FROM = 2026-10-18 since 0.13.2, the day
after screen-locker's late-credit rule shipped): each rung pays what
its earner pays in gaming (workout 120, LeetCode 60, reading 60, tutor 1/unit
to 60), so the floor drops 18:50 -> 18:00 under the same 23:00 ceiling:
nothing 3 h / 18:00, workout 5 h / 20:00, +LeetCode 21:00, +reading 22:00.
Sick days (0.13.0, _sick.py). resolve(..., sick=True) shuts down at
20:00 (SICK_SHUTDOWN_FLOOR_MINUTES) plus every term's gaming pay, capped
at the ceiling: LeetCode + reading is 22:00 (0.11.0's non-stacking max gave
20:10). Never below 0.11.0's max(20:00, earned), so it landed same-day.
Base, terms, gaming, waivers and penalties are unchanged; earners still earn.
sick is the consumer's answer (sickdays.is_sick_day, never imported here).
A live consumer raises the config to the sick resolution after each credit.
The tutor cutover (TUTOR_FROM, one constant in _ladder.py). The
registry is per day: earners_for(day) is EARNERS before it and
TUTOR_EARNERS from it. From TUTOR_FROM Anki is retired (neither penalised
nor paid) and the tutor is TUTOR (name tutor), a counted earner on the
tutor's ledger (~/.local/share/tutor/ledger.json, tutor_match on
detail.ended_at). Until 0.9.0 it was AUTOMATION_TUTOR (name automation,
its own ledger, copied whole on the rename: old rows still pay).
Since 0.8.0 it pays per active minute (a unit is one minute), at most 60
a day summed across sessions.
Weekday quota (0.10.0, TUTOR_QUOTA_FROM 2026-10-12, _quota.py): all 60
units take 15 min Tue-Thu (WORKDAYS, a copy of freedays'), 30 Mon/Fri, 50
Sat/Sun; credit_units scales the day's deduped minute sum,
min(60, minutes * 60 // quota), so it returns units, no longer minutes:
| units | gaming | shutdown rung |
|---|---|---|
| each minute | +1 min | +1 min (Rung(1, extra=1)) |
| all 60 | +60 (Anki's 30 folded in) | +60 (Anki's 25 folded in) |
Each minute earns exactly the shutdown it costs (the fairness rule). Once its
penalty has started, the gaming base drops by the full 60
(Earner.max_gaming_minutes) and the ladder floor by the full 60, so nothing
done is 3 h / 18:50 and everything done is still 8 h / 23:00. Until then
(given first_credits, see below) it costs nothing: 4 h / 19:50.
The tutor row contract (0.8.0, mixed-day safe) — detail.minutes, one row per
credited minute, the legacy 15-minute block, an entry_id paying once and what
the writer must guarantee: DOCS-tutor.md.
Gap waiver (ANKI_WAIVED_FROM, 2026-10-09): no anki/automation earner.
No gaming budget (0.22.0)
kuhy's decision, 2026-11-16: the stick of gaming time is gone; only shutdown
is the carrot (all locks done = 23:00, the ladder is unchanged). One dated
switch, GAMING_UNLIMITED_FROM (2026-11-16, a gaming day), and
gaming_enforced(day) -> bool (day < GAMING_UNLIMITED_FROM), also carried as
Resolution.gaming_enforced. Nothing was removed: gaming_minutes, GAMING_*
and the leisure API still resolve numbers, so old imports keep working, but
from the switch they are history, not a limit. A consumer that applies a
budget must read the switch and lift its limit on False.
leisure_active(day)isFalsefrom the switch (no budget to be a leisure one);resolve/base_forwithleisure=Nonethen use the old base.- A sick day's shutdown is 20:00 plus the credited terms' shutdown (rung) 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.
Partial pay (0.24.0)
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, 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 review
excepted. The row, the reader and every fail-closed case are in
DOCS-progress.md. The review differs from REVIEW_PROGRESS_FROM (2026-11-24): a credited review
pays only by its row (20 * done // target), and with no verified row pays 0.
Gate maturity (0.6.0)
How far to trust a gate, computed from its ledger by maturity(), is in
DOCS-maturity.md.
API
resolve(answers, day=None, earners=None, *, first_credits=None, sick=False, leisure=None, progress=None) -> Resolution— the one sum.sick_shutdown_from(paid_minutes, day) -> int.base_for(day=None, earners=None, *, first_credits=None, leisure=None) -> Base— the day's floors.gaming_base_minutes_for(day),gaming_ceiling_minutes_for(day) -> int— the gaming base and cap.leisure_from(path=LEISURE_FROM_PATH) -> date,leisure_active(day, path=...).gaming_enforced(day) -> bool,GAMING_UNLIMITED_FROM(0.22.0).done_today(earner, ledger, key_file, *, now=None) -> bool | Nonefirst_credit_at(earner, ledger, key_file, day) -> float | None— unix time of the earliest verified credit forday, on its matcher's stamp (_match.CREDIT_STAMPS; elsecreated_at); it can lie outsideday.credit_units(earner, ledger, key_file, day) -> int | None— the units the verified rows pay forday: 1 per row (the workout), or the row's own count (detail.minutes: tutor, legacy blocks 15, from 0.10.0 scaled to its weekday quota; focus). A repeatedentry_idpays once;resolveappliesmax_units.earners_for(day),all_earners(),registries()— the registry in force on a day, and every earner of every registry (what a ledger watcher must watch). They readearned_time.EARNERSthrough the package, so a patch holds.shutdown_minutes_for(earner, day),extra_shutdown_minutes_for(earner, day),shutdown_ceiling_for(day)(ints),on_ladder(day) -> bool— what a status view lists as still left to earn.Earner.shutdown_for(units, day=None)is the day-aware sum. Never readearner.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.topupandEarner.evidence(0.23.0).progress_map(day, home, key_file, *, earners=None, gate_off=()) -> dict[str, Progress],read_progress(earner, ledger, key_file, day, *, gate_off=False) -> Progress | None,Progress(done, target),Earner.progress_source,Term.progress,REVIEW_PROGRESS_FROM(0.24.0).
The workout ledger
WORKOUT is kind="counted", ledger ~/.local/share/workout_locker/ledger.json
(screen-locker; one signed credit row per unit, detail.completed_at/source).
workout_match counts a runnerup_tcx row by completed_at, a rest_day row
on its day only if detail.declared_at predates that day (else logged, no).
The focus project (0.19.0, cut 180 since 0.20.0, pays 240 since 0.21.0)
While focus_project.active(day) returns a project, earners_for drops the
gates it replaces (book = reading) and adds one counted focus earner
(max_units = the day's daily_on). Shutdown pays their rungs (180/120 min); gaming
their max_gaming_minutes + pure bonuses again (240/120 min = 2/min; full day = 8 h):
floor(summed minutes * pay / daily_minutes), never per row. The penalty runs
from the start day, cutting all of it, 180 with LeetCode's formerly free hour (0.20.0); maturity never delays it. Ledger ~/.local/share/focus_project/ledger.json:
signed credit rows, entry_id <project>-<YYYYMMDD>-m<n>, detail.minutes (positive int),
detail.ended_at (else day). focus_project unusable = no project (logged).
Unbacked timer time pays 0 from 2026-11-08 (focus_project 0.10.0).
Adding a gate
-
The gate writes
{"entries": [...]}to its ledger. Each row haskind: "credit", adetaildict, and anhmacsigned with/etc/workout-locker/hmac.key(earned_time.entry_signature, the same as gatelock'slog_integrity). -
Add a matcher to
earned_time/_match.pyand anEarnertoearned_time/_policy.pyandEARNERS:PIANO = Earner( name="piano", # also screen-locker's "piano_bonus_date" stamp gaming_minutes=30, shutdown_minutes=30, # pre-ladder value penalty_from=date(2026, 11, 1), # gaming base drops by 30 from then on ledger=".local/share/piano_guard/ledger.json", match=piano_match, # which verified credit rows count today )Then a rung in
TUTOR_LADDER(PIANO.name: Rung(20)) and, for an event stamp, an entry in_match.CREDIT_STAMPS.A new rung comes out of the floor from its penalty start (a pure bonus: the day its pin lands): ship it the day the gate can be satisfied.
-
Bump, tag
earned-time-vX.Y.Z, re-pin every consumer (no code needed).
Rules the consumers rely on
- Minutes everywhere. Shutdown is minutes after local midnight.
- Paths are passed in. Only the switch file is resolved here
(patch
earned_time._leisure.LEISURE_FROM_PATH). Noneis "could not check", never "no". It earns nothing (fail closed), but consumers log it. A missing answer inresolve()is logged as well; an unknown earner name raises.- The HMAC key is root 0644 on purpose. User-run gates sign rows with it; it stops casual edits, not a determined forger with a shell.
- Stdlib only. The root gaming daemon imports this headless;
focus_project(stdlib too) is imported lazily and may be absent.
Install
pip install --user --break-system-packages --no-deps "earned-time @ git+https://github.com/kuhyx/utils@earned-time-v0.24.0#subdirectory=earned_time"
The root steam-backlog-enforcer.service sets HOME=/home/kuhy and imports from
the same user site-packages. Test: scripts/run_subproject_tests.sh earned_time.