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>
4.3 KiB
sickdays: sync and the wire format (for the phone)
Firebase RTDB only, shared credential ~/.config/crdt-sync/ (crdt-sync's
firebase_client_for("sickdays")). One directory per device; each device
writes only its own node:
| RTDB node | value |
|---|---|
sickdays-sync/devices/<uuid>/sick_days~2Ejson |
a JSON string holding the log (below) |
sickdays-sync/revs/<uuid> |
hex SHA-256 of that exact string |
The logical path is sickdays-sync/devices/<uuid>/sick_days.json. crdt-sync
escapes the . in keys as ~2E. Write the log first, then the rev; a peer
skips any device whose rev it has already merged. The <uuid> is a
persisted per-install uuid4, never pc/phone.
The log is a JSON object keyed by ISO date. Each value is a crdt-sync record:
{
"2026-10-20": {
"id": "2026-10-20",
"fields": {
"state": ["sick", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"actor": ["<uuid>", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"keep": [["leetcode", "workout"], "2026-10-16T08:12:03.517Z-0000-<uuid>"]
},
"deleted": false,
"deleted_hlc": null
}
}
idequals the key:YYYY-MM-DD, local date.stateis"sick"or"cleared". Anything else, or a missing record, means a normal day.actoris the uuid of the device that last wrote it.- Each field is
[value, hlc], and every field of one write carries the same HLC. The HLC string isYYYY-MM-DDTHH:MM:SS.mmmZ-<counter, 4 hex>-<node uuid>(UTC wall time). It orders as the tuple(wall_ms, counter, node_id). A new tick ismax(now_ms, last_own.wall_ms), with the counter bumped when the wall time did not move. - Merge = per-field last-writer-wins: for each date, keep the field with the greater HLC. So the latest add or remove of a date wins on every device, and a date can be added and removed any number of times.
- Remove = write
state: "cleared". Never writedeleted: true. crdt-sync OR-merges tombstones, so a deleted date could never be marked sick again. A tombstoned record reads as "not sick".
keep (0.2.0)
keep is [<list of locker-id strings>, <hlc>]. The list is sorted
(plain string order) and de-duplicated, always: the rev is a SHA-256 of
the exact JSON string, so two devices holding the same set must write the
same bytes. Ids: workout, leetcode, book, diet, alarm.
Writing:
- add (mark sick) writes
state: "sick",actorandkeep(default[]), all three with the same HLC tick, always. So a stalekeepfrom another device cannot survive a clear and a re-add. - remove writes
state: "cleared",actorandkeep: [], same tick. - change kept lockers on an existing sick day does not touch
state: copy the record, stamp onlykeepandactorwith one fresh tick, and leavestate(and its HLC) as it was. Re-stampingstatewould make a keep edit re-assert "sick" over a concurrent clear. Only today or later, only on a day that is currently sick. - Every new tick is issued after both this device's last tick and the
greatest HLC already on that day's record, so an edit never comes out
older than the
stateit was made against.
Reading (a locker stands down iff the day is sick and the locker is not in the keep set), checked in this order:
- Day not sick (no record, tombstone, state not
"sick", unreadable pool) -> nothing stands down;keepis not looked at. - No
keepfield (every 0.1.0 record) -> keep nothing: every locker stands down. keep's HLC is older thanstate's HLC -> stale (an old 0.1.0 client re-added the day) -> keep nothing. Equal HLCs are not stale.keep's value is not a list, or holds a non-string element -> malformed -> fail closed: every locker is kept (nothing stands down), and a warning is logged. (A stale malformed value is just stale: rule 3 wins.)- Otherwise the kept set is the list, with unknown string ids ignored (forward compatibility), not an error.
Don't hand-roll this on Dart: use crdt_sync_dart (syncLog, logToJson
/ logFromJson), exactly as wake-alarm's free_day_sync.dart does for
freedays-sync. Only the prefix (sickdays-sync/devices), the filename
(sick_days.json) and the "sick" state value differ. There is no
consumed or reason field. The phone must follow the keep rules in README.md.