Skip to main content

CRDT conflict semantics — learner-model

The current learner-model uses Loro-backed storage and schema 1.1.0. substrate/learner-model/src/store.rs owns normalization and derived-state folds; types.rs owns persisted field shapes. The former Automerge/LWW design is superseded and must not guide current writes.

Evidence, not merged counters​

Concept observations are keyed by stable observation ID. The fold sorts them by timestamp and ID, then derives mastery and FSRS state from immutable priors. Reimporting the same evidence does not add an observation merely because it arrived from another device. Distinct observations remain distinct even when their score and source happen to match.

Mastery stays at its prior before the fifth observation. From that observation onward the fold applies mastery + 0.3 * (score - mastery), clamped to [0, 1]. Review observations advance scheduling through their recorded rating and timestamp; the derived due date is the earliest review-derived date, or the prior due date when no review exists. Repetition and lapse counts cannot fall below their priors. Do not write independent mastery or FSRS counters as competing replicated facts.

Sessions are deduplicated by session ID, keeping the record with the later ended_at, then sorted by start time and ID. Gaps remain keyed by gap ID; load, save and import normalize key/record identity.

Recoverable migration​

Older observation arrays become keyed evidence. Missing legacy IDs are derived from canonical content and position. Before a migrated document replaces the old snapshot, the store retains its original bytes at learner/<learner-id>/migrations/pre-1.1-<blake3>.loro. Keep these backups and verify the actual import/replay boundary before claiming convergence on an update.

See Loro evidence and migration for the reader-facing reference. These are source contracts; existing unit or property checks do not certify the current phase. Run the appropriate local integration only after all production changes are complete.