utils/sickdays/DOCS-sync.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

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
  }
}
  • id equals the key: YYYY-MM-DD, local date.
  • state is "sick" or "cleared". Anything else, or a missing record, means a normal day. actor is 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 is YYYY-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 is max(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 write deleted: 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", actor and keep (default []), all three with the same HLC tick, always. So a stale keep from another device cannot survive a clear and a re-add.
  • remove writes state: "cleared", actor and keep: [], same tick.
  • change kept lockers on an existing sick day does not touch state: copy the record, stamp only keep and actor with one fresh tick, and leave state (and its HLC) as it was. Re-stamping state would 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 state it 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:

  1. Day not sick (no record, tombstone, state not "sick", unreadable pool) -> nothing stands down; keep is not looked at.
  2. No keep field (every 0.1.0 record) -> keep nothing: every locker stands down.
  3. keep's HLC is older than state's HLC -> stale (an old 0.1.0 client re-added the day) -> keep nothing. Equal HLCs are not stale.
  4. 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.)
  5. 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.