screen-locker/docs/todo/DOCS-workstream-d-scoping-findings.md

# Workstream D — scoping pass findings (2026-07-04)

Answers the four scoping questions from `workstream-d-shared-crdt-transport.md`,
based on reading the actual code in all four repos (not the prior doc's
summaries) and researching current Python CRDT packages. No code was written
or modified in any repo for this pass, per that doc's explicit instruction.

## Headline finding: "shared CRDT transport library" is two separable things

The original doc bundles **transport** (how bytes move between devices) and
**merge** (how conflicting data reconciles) into one library. They turn out
to have very different shareability:

- **Transport** (GitHub Contents API client: `get_file_text` /
  `put_file_text` / `list_directory` against a private repo) is genuinely
  shared already — it's independently duplicated almost line-for-line
  between todo's `GitHubClient` and diet-guard's `GitHubSyncClient`
  (`~/src/diet-guard/diet_guard/_sync_github.py`, 191 lines, `requests`-only).
  Extracting this into a shared Python lib (and a shared Dart lib for
  todo's/diet-guard's Dart-side client) is low-risk, small, and is the part
  Workstream C already committed to (Contents-API pattern, not Gist —
  see `workstream-c-github-sync-workout-data.md`).
- **Merge** is *not* uniformly shareable — see next section. Treating "pick
  one CRDT scheme for all four apps" as a single decision undersells that
  todo and the other three apps are solving different problems.

Recommendation: split the library (or at least the decision) along this
seam. Extract shared transport now; treat "one unified merge scheme" as a
separate, larger, and more questionable decision (see "Sub-decisions" below).

## 1. Python CRDT landscape check

Checked PyPI for currently-maintained options (search run 2026-07-04):

| Package | Status | Fit |
|---|---|---|
| `pycrdt` | Actively maintained (0.14.1, June 2026), owned by Project Jupyter | Bindings for Yrs (Rust Yjs port). Built for rich collaborative documents (maps/arrays/text with binary Yjs encoding) — the same engine behind JupyterLab real-time collaboration. Wrong shape for this use case: output isn't git-diffable JSON, has no SQLite/flat-file integration, and models a fundamentally richer editing problem (concurrent character-level text edits) than "append a log entry, sometimes delete one." Adopting it would mean encoding every log entry into a Yjs doc and pushing an opaque binary blob to GitHub instead of the current human-readable JSON — a downgrade in debuggability for no benefit these apps need. |
| `crdts`, `python3-crdt`, `crdt-py` | No PyPI release in 12+ months each — effectively unmaintained | Implement classic primitives (G-Set, OR-Set, LWW-Element-Set, PN-Counter) which are closer in shape to what's needed, but taking on an unmaintained external dependency for a handful of well-understood, stable algorithms is a worse trade than owning the ~80 lines directly. |
| `cr-sqlite` | Actively maintained, but is a native loadable SQLite *extension*, not a Python package — usable from Python's `sqlite3` module once compiled/loaded | Would require migrating diet-guard/screen-locker/wake-alarm's storage from flat JSON files to SQLite first. None of them store data in SQLite today. That's a materially bigger, unrelated migration bundled into this workstream — out of scope unless the user wants to widen it. |

**Conclusion: no third-party package fits "CRDT over a flat, git-diffable
JSON log" well.** The pragmatic answer isn't "adopt X" or "hand-roll a CRDT
from scratch" (the doc's original framing) — it's **formalize what
diet-guard already built**. `diet_guard/_sync_merge.py`'s entry-id-keyed,
tombstone-wins merge (mirrored test-for-test in
`app/lib/services/sync_merge.dart`) already has the properties a CRDT needs
here — commutative and idempotent per its own docstring and the mirrored
Python/Dart test suites — *given one constraint*: entry bodies are never
mutated after creation, only `deleted`/`hmac` change. That's a **remove-wins
register per entry**, not a general add-wins OR-Set, and it works precisely
*because* diet-guard's and screen-locker's data is an append-only log of
otherwise-immutable entries. Extracting this ~80-line scheme into the shared
Python lib (and its Dart mirror into the shared Dart lib) is a small,
low-risk task with a working reference implementation and existing tests to
port, not new CRDT design.

## 2. Transport primitive decision

**Contents-API repo pattern**, not Gist. This was already decided for
Workstream C and this pass confirms it's the right call for the shared
library too:

- todo and diet-guard already both use a Contents-API-shaped client
  independently (private repo, `listDirectory`/`getFileText`/`putFileText`)
  — it's the de facto standard across this user's repos already, not a new
  choice.
- wake-alarm is the only Gist user, and (see sub-decision 2 below) its data
  shape doesn't need what the shared library is for in the first place.

## 3. Per-app migration cost (revised — the original doc's "todo = smallest
lift" assumption does not hold)

Checked `~/src/todo/lib/data/note_repository.dart`: notes are **mutated in
place** — `upsert()` does `INSERT ... ON CONFLICT DO UPDATE SET text = ?,
priority = ?, status = ?, updated_at = ?`, relying on `sqlite_crdt`'s
per-column Hybrid-Logical-Clock last-writer-wins to reconcile concurrent
edits to the *same* note's *same* fields. This is a genuinely different CRDT
problem from diet-guard's/screen-locker's append-only, immutable-once-written
log entries. A shared scheme built around diet-guard's tombstone approach
(section 1) does not cover todo's need without significant extension
(effectively re-deriving field-level LWW/HLC in the shared lib) — and
`sqlite_crdt` already solves todo's exact problem well today.

| App | Data shape | Current state | Migration cost if unified merge scheme required | Migration cost if shared transport only |
|---|---|---|---|---|
| todo | Mutable records, per-field edits | `sqlite_crdt` (HLC-based, mature, in production) | **L** — would need the shared lib to grow field-level LWW to match what it already has, i.e. reimplement `sqlite_crdt`'s core in the shared lib for no behavior gain | **S** — keep `sqlite_crdt` for merge, optionally swap its transport for the shared client |
| diet-guard | Append-only log, tombstoned deletes, immutable bodies | Hand-rolled tombstone merge (Python + Dart, mirrored) | **S** — this *is* the reference implementation to extract | **S** — same, transport already Contents-API-shaped |
| wake-alarm | Single current scalar (next wake time), single writer, no history | No merge logic at all (Gist overwrite) | **M–L** for no behavioral gain — see sub-decision 2 | **S** if just swapping Gist → Contents-API for transport consistency; **none needed** if left as-is |
| screen-locker | Append-only log (workout entries), net-new sync | Nothing exists yet | **S** — greenfield, adopts whatever the shared lib provides directly | **S** — same |

## 4. Sequencing relative to Workstream C

The prior "C waits for D" decision was made when D was "not started, not
scoped" (2026-07-04, same day). This scoping pass changes what's actually
being waited on: the *transport* piece (what C needs first — Contents-API
client) is small, low-risk, and effectively already designed by example in
diet-guard's `_sync_github.py`. The *merge-unification* question (does one
scheme cover all four apps, per sub-decision 1) is the open, larger piece —
and screen-locker's own data (an append-only workout log, same shape as
diet-guard's) doesn't actually need that question resolved first, since the
diet-guard-style tombstone scheme already fits it directly.

**Flagging, not deciding:** it may be possible to unblock Workstream C on
just the shared transport client + the diet-guard-style merge scheme,
without waiting for a resolution on whether/how todo's different merge
problem folds into the "shared" library. That's a sequencing option to
confirm with the user, not something this pass resolves unilaterally.

## Sub-decisions — resolved (2026-07-04, user call, overriding this doc's recommendations)

Both sub-decisions below were put to the user with an explicit recommendation
each way this pass leaned against; the user considered the trade-off and
decided the other way on both. Recorded here as settled, not open:

1. **One unified merge scheme, covering all four apps including todo.**
   This means the shared library's merge scheme must be extended beyond the
   diet-guard-style tombstone-log scheme to also handle todo's mutable,
   per-field-edited notes — i.e. it needs to grow something equivalent to
   `sqlite_crdt`'s per-column HLC last-writer-wins, in Python and Dart, not
   just the simpler append/tombstone case. This is materially more design
   and implementation work than the transport-only extraction (was flagged
   as **L** cost in the table above) — budget for it accordingly when this
   moves to an implementation plan.
2. **wake-alarm converts to CRDT merge too**, despite its data (single
   current wake-time value, one writer, no history) having no actual
   concurrent-edit conflict for a CRDT to resolve. This is consistency-driven
   rather than need-driven — noted so a future implementer isn't confused
   about why a single-scalar value is running through CRDT merge logic; it's
   an intentional choice, not an oversight.

Net effect on scope: this makes Workstream D closer to its original framing
(one CRDT scheme, all four apps) than the leaner split this pass initially
recommended. The Python-CRDT-landscape conclusion from section 1 still holds
regardless — no third-party package fits, so the unified scheme is still
something to build by generalizing diet-guard's approach and folding in
per-field LWW for todo/wake-alarm's single-value case, not something to pull
off the shelf.

## Critical files referenced (read-only during this pass)

- `~/src/todo/lib/sync/sync_service.dart`, `~/src/todo/lib/data/note_repository.dart`
- `~/src/diet-guard/diet_guard/_sync.py`, `_sync_github.py`, `_sync_merge.py`
- `~/src/diet-guard/app/lib/services/sync_merge.dart`
- `~/src/wake-alarm/shutdown-wrapper.sh`
- `docs/todo/workstream-c-github-sync-workout-data.md` (this repo)