mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-22 19:52:27 +01:00
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
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
term_for(earner, day, *, answer, progress=None) returns the Term an earner pays: the ladder rung, the share of a row, the full-pay cap and the review's dated rule. resolve builds every term through it, so a consumer pricing one earner cannot disagree with resolve and never re-derives a share. A grid test pins term_for == resolve's term for every earner, answer, row and day either side of REVIEW_PROGRESS_FROM, and a second test checks the minutes against the written rules, not the library code. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxdWZLyjnLjB1THD6ckou
243 lines
14 KiB
Markdown
243 lines
14 KiB
Markdown
# 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](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](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](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.
|
||
One earner's pay for a day is `term_for(earner, day, *, answer, progress=None)`,
|
||
the code `resolve` itself uses: consumers never re-derive a share.
|
||
|
||
## Gate maturity (0.6.0)
|
||
|
||
How far to trust a gate, computed from its ledger by `maturity()`, is in
|
||
[DOCS-maturity.md](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`, `REVIEW_PROGRESS_FROM`,
|
||
`term_for(earner, day, *, answer, progress=None) -> Term` (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`:
|
||
|
||
```python
|
||
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
|
||
|
||
```console
|
||
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`.
|