- Status: approved (2026-07-18)
- Priority: P0 EXT — blocking (production rollout gated via YSD-0139)
- Decision owner: @GreyChimp
- Drafted: 2026-07-18 by Claude Code (claude-fable-5)
- Approval: approved as recommended by @GreyChimp on 2026-07-18; outcome recorded in decision-log.json; review by 2027-07-18
Question#
CRDT, lock/lease, or bounded hybrid for co-annotation, offline queues, and live sessions?
Recommendation#
Explicitly bounded hybrid: CRDT-mergeable draft layers for annotations, notes, and offline queues (drafts are commutative and low-conflict); lease-based single-writer editing for accepted-record supersession, rights decisions, and comparison-set freezes (append-only history must not merge); live co-study sessions use presence + shared playback clock with per-object leases. The boundary is contractual: anything with review state acceptance semantics is lease-gated; anything draft is CRDT.
Options considered#
- Pure CRDT — rejected: accepted/immutable records (YSD-0013) cannot be last-writer-merged without corrupting review history.
- Pure locking — rejected: kills offline note capture and fluid co-annotation.
Consequences#
- Section 8 collaboration items implement per this boundary; persistence (YSD-3005) implements optimistic concurrency for drafts and append-only acceptance.
Machine-enforced outcome (once approved)#
Contract-level marker (draft vs accepted) selects the mechanism; tests prove accepted records never CRDT-merge.