utils/earned_time
Krzysztof kuhy Rudnicki 644d372625 Read progress from the last good row
The day's last verified progress row for the source wins, and both done
and target come from that one row. max(done) with max(target) could pair
a stale target with a new done when a gate re-derives its target within
a day (book-guard does). The rule reads neither created_at nor device,
which the workout ledger does not write.

A later row that fails verification, has the wrong kind, source or day,
or has unreadable numbers is skipped; no good row is still None. The
public API, the version and every other behaviour are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZLyjnLjB1THD6ckou
2026-11-22 18:44:20 +01:00
..
earned_time Read progress from the last good row 2026-11-22 18:44:20 +01:00
scripts earned_time 0.9.0: tutor earner renamed AUTOMATION_TUTOR/automation -> TUTOR/tutor, ledger ~/.local/share/tutor 2026-10-12 16:31:50 +02:00
.pre-commit-config.yaml Clear inherited CI debt in the Python libs 2026-11-16 08:58:01 +01:00
DOCS-maturity.md Clear inherited CI debt in the Python libs 2026-11-16 08:58:01 +01:00
DOCS-progress.md Read progress from the last good row 2026-11-22 18:44:20 +01:00
DOCS-review.md earned_time: 0.23.0, document the review top-up 2026-11-21 22:09:35 +01:00
DOCS-tutor.md Pay partial progress in earned_time 0.24.0 2026-11-22 18:24:22 +01:00
pyproject.toml Pay partial progress in earned_time 0.24.0 2026-11-22 18:24:22 +01:00
README.md Read progress from the last good row 2026-11-22 18:44:20 +01:00
requirements.txt get rid of github ci/cd version check of package… 2026-11-19 18:11:07 +01:00

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's shutdown_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 (a Rung per earner name; all of a counted earner's capped units), so doing everything lands exactly on the ceiling. Since 0.6.1 TUTOR_FROM == LADDER_FROM, so every real ladder day uses TUTOR_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.extra defaults to 0). Move the alarm (WAKE_MINUTES = 6 * 60) and the whole ladder shifts an hour earlier on its own. Days before LADDER_FROM keep 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) is False from the switch (no budget to be a leisure one); resolve/base_for with leisure=None then 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 row, the reader and every fail-closed case are in DOCS-progress.md.

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 | None
  • first_credit_at(earner, ledger, key_file, day) -> float | None — unix time of the earliest verified credit for day, on its matcher's stamp (_match.CREDIT_STAMPS; else created_at); it can lie outside day.
  • credit_units(earner, ledger, key_file, day) -> int | None — the units the verified rows pay for day: 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 repeated entry_id pays once; resolve applies max_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 read earned_time.EARNERS through 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 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).
  • 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 (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

  1. The gate writes {"entries": [...]} to its ledger. Each row has kind: "credit", a detail dict, and an hmac signed with /etc/workout-locker/hmac.key (earned_time.entry_signature, the same as gatelock's log_integrity).

  2. Add a matcher to earned_time/_match.py and an Earner to earned_time/_policy.py and EARNERS:

    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.

  3. 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).
  • None is "could not check", never "no". It earns nothing (fail closed), but consumers log it. A missing answer in resolve() 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.