utils/earned_time/DOCS-maturity.md
Krzysztof kuhy Rudnicki c29d0989dd Clear inherited CI debt in the Python libs
main was red on file length, the noqa ban, codespell, test naming and
dart coverage; this change touches every one of those jobs.

- sickdays: set_enabled is keyword-only; the panel test splits in two
  with shared probes; the sync wire format moves to DOCS-sync.md.
- earned_time: _focus types the project as a Protocol, no noqa; the
  gate-maturity section moves to DOCS-maturity.md; codespell knows the
  `checkin` event name.
- focus_project: real fixes for every noqa (local-day clocks, typed
  fakes, logged broad catches, split helpers). The public API that
  focus-guard calls keeps its signatures; their PLR0913 exemption
  lives in pyproject with the reason, not in noqa.
- crdt-sync: pylint gets nacl/argon2, docstrings, and allows the
  public E2eLayout.of; _blobs moves to _e2e_blobs.py.
- crdt_sync_dart: Argon2Params and the header errors move to
  e2e_params.dart (re-exported); tests split and reach 100% lines.
- sql_drills: test helpers get a leading underscore, as in earned_time.

Todo: fda71ed1
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 08:58:01 +01:00

2.2 KiB

earned_time: gate maturity (0.6.0)

How far to trust a gate is computed from its ledger, never listed by name: maturity(earner, ledger, key_file, today) -> Maturity (_maturity.py).

  • Real credit: HMAC-verified credit row, accepted by the earner's match, not manual (detail.source manual/manual_grant, entry_id manual:/manual_grant:), and amount > 0 when the row has one -- a gate's own re-evaluation grant (detail.grant_of, book-guard bonus: rows) may pay 0. A matcher cannot loosen this (anki_match alone accepts a manual_grant row).
  • Levels: new = no real credit, or no Earner.confirmed_on (set by kuhy); mature = at least MATURE_MIN_CREDIT_DAYS (14) distinct credit days and the first at least MATURE_MIN_AGE_DAYS (21) old; else maturing. An unreadable ledger or key is checked=False, new, reason recorded.
  • Penalty start: penalty_start(earner, first_credit) = max(penalty_from, day after the first real credit, day after confirmed_on). No first credit (never paid out, or could not check) is not penalised -- unless confirmed_on is set: then fail closed, max(penalty_from, day after confirmed_on), so deleting or locking a ledger cannot lift a penalty. Pass first_credits={name: Maturity.first_credit}, computed over earners_for(day) (until 0.9.0 two earners shared the name automation), to resolve / base_for to apply it; omitted, a penalty starts at penalty_from, as in 0.5.0. It can only delay a penalty, never add one.
  • Ladder floor (0.6.1): the same start gates the shutdown floor. A rung comes off the floor only for a pure bonus (no penalty_from: workout, LeetCode) or an earner whose penalty has started, so a gate that never paid out cannot lower it either (10-10, tutor never credited: 19:50, not 19:00). An unwired consumer (no first_credits) cuts the tutor from penalty_from: 19:00 / 3 h.
  • CLI: python -m earned_time maturity [--json] [--day YYYY-MM-DD] prints one row per ledger-backed earner of every registry. It and leisure_from() alone resolve real paths (~/<Earner.ledger>, /etc/workout-locker/hmac.key), and it only reads.