utils/earned_time/DOCS-tutor.md
Krzysztof kuhy Rudnicki e5e457d8a9 Pay partial progress in earned_time 0.24.0
A gate can now sign "done N of target M for day D" and resolve() pays a
no-answer that share of a yes (60 * 1 // 3 = 20), floored, for shutdown,
gaming and sick days. A yes still pays full; "could not check" still pays
nothing. With no progress row anywhere every output is 0.23.0's, pinned by
a digest grid and, when installed, the real 0.23.0 as oracle.

Every failure reads as no progress, so the day pays by its yes/no rule and
never more:
- no row, a bad or missing signature, an edited row
- another day or another gate's source
- numbers typed as ints, floats, signed, padded, empty, non-ASCII or huge
- a zero target (no plan, no share)
- an unreadable key or ledger (logged, never raised)
- the gate being off today
- an earner with no progress source (tutor, focus)
A bad row beside a good one is skipped. Done above target is capped.

The focus earner now uses the same share arithmetic, same floor. A progress
row is not a credit: maturity and the done answers never see it. The floor
helpers moved to _floor.py and the tutor row contract to DOCS-tutor.md to
stay under the 250-line cap.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWVfmEXxPymCs5bo3Zs
2026-11-22 18:24:22 +01:00

32 lines
1.8 KiB
Markdown

# The tutor row contract (0.8.0)
Moved out of the README (0.24.0) to keep it under the line cap; unchanged.
**Mixed-day safe.** `credit_units` sums what
each counting row pays instead of counting rows (`_credits.row_units`, the
per-matcher reader `_match.ROW_UNITS`):
- `detail.minutes` (a positive JSON int, never a bool/float/string) is the
active minutes the row pays. A row **without** it is a 0.7.0 15-minute
block and pays 15 (`LEGACY_TUTOR_MINUTES`), so a day that mixes block rows
and minute rows sums both, and an all-block day resolves exactly as 0.7.0
did (min(15 n, 60) = 15 min(n, 4)). A row whose `minutes` is present but
invalid is refused by `tutor_match` (logged) and pays nothing anywhere.
- An `entry_id` pays once; rows repeated under one id pay the **smallest**
of their counts, so a replay or a rewrite can never raise a credit.
- What the writer ([kuhyx/tutor](https://github.com/kuhyx/tutor) `tutor/credit.py`) must guarantee: every
new row carries `detail.minutes`; one row per credited minute,
`entry_id = f"{session_id}-m{n}"` with `n` the session's n-th credited
active minute (deterministic, so a retry rewrites the same id; never the
`-b{n}` form); ids never cover overlapping minutes (no cumulative "total so
far" rows); `detail.ended_at` is when the last paid minute ended (it picks
the day, so a multi-minute row must never span local midnight); its own
daily cap sums minutes (block rows as 15) up to 60. N-minute rows (e.g.
every 5 minutes) are allowed under the same rules; each write fires
screen-locker's `earner-bonus.path`, so per-minute rows rewrite the
shutdown schedule once a minute.
Days before `TUTOR_FROM` resolve on `EARNERS` exactly as before. Consumers must
iterate `earners_for(day)`, never `EARNERS`; `resolve`/`base_for` default to
it, and ignore answers for an earner of another day's registry.