docs/sync-and-op-log/README.md
The Operation Log is the single client sync pipeline for SuperSync and file providers. Persistent NgRx actions update the live projection and are captured as durable operations; restart uses a structurally screened snapshot plus the retained operation tail. Vector clocks detect causal order and concurrent edits.
Persistent NgRx action
┌────────┴────────┐
▼ ▼
NgRx reducers operation capture
│ │
▼ ▼
runtime projection SUP_OPS
(ops, clocks,
checkpoints, snapshot)
│
▼
Sync Providers
┌───────────────────┴──────────────────┐
▼ ▼
SuperSync File providers
(ordered op API) (shared v2 or v3 envelopes)
The v2/v3 envelopes are common adapter formats, not a common physical write guarantee. Dropbox and OneDrive can enforce API compare-and-swap (CAS), while WebDAV/Nextcloud is atomic only when the server supplies strong ETags; weak or missing ETags fall back to a best-effort check. LocalFile likewise has a best-effort read/check/write race and is single-writer/backup-only.
Current mechanics live in the executable owners linked by these documents. Overview and history documents explain the model but do not override code, tests, or a focused contract.
| You want to… | Read |
|---|---|
| Build a five-minute whole-system mental model | sync-architecture.html — standalone maintainer field guide; open the local file in a browser |
| Write an effect/reducer/bulk-dispatch correctly | contributor-sync-model.md — the one invariant, drop-vs-defer selector rule, and lint boundaries |
| Compare SuperSync and file v2/v3 | field guide: transports |
| Trace remote apply, conflicts, or restart recovery | remote apply, causality, restart |
| Change SECTION conflict/recovery behavior | section-conflict-replay.md — narrow commutativity, state-projected replay, and released-client compatibility contract |
| Find executable coverage for a SuperSync scenario | supersync-scenarios.md — scenario-to-test index, not a prose specification |
| Research rejected alternatives or cross-version policy | operation-log-architecture.md — deep rationale and history plus the normative A.7.11 schema-bump policy |
| Status | Document | Scope |
|---|---|---|
| Overview | sync-architecture.html | High-level maintainer map: local intent, transports, crash-safe apply, causality, exceptional boundaries, restart recovery, and executable owners |
| Contract | contributor-sync-model.md | Contributor invariant: one replay-atomic transition = one op; replayed/remote ops must not re-trigger effects |
| Contract | section-conflict-replay.md | SECTION conflict commutativity, state-projected semantic replay, atomic replacement, and released-client compensation |
| Contract | package-boundaries.md | Dependency/ownership boundaries for @sp/sync-core, @sp/sync-providers, app wiring |
| Contract | conflict-journal-and-review.md | Disjoint-field auto-merge plus the dormant device-local journal/review capability and its security boundary |
| Contract | persisted-model-fields.md | Adding fields to persisted models: optional-plus-default invariant, heal paths, and the latent hydration-validation failure (#8965) |
| Contract | vector-clocks.md | Vector-clock implementation, storage/pruning ownership, and history |
| Contract | supersync-encryption-architecture.md | End-to-end encryption wire format, key lifecycle, integrity boundary, and known limitations |
| Mixed | operation-log-architecture.md | Deep rationale and implementation history plus the normative A.7.11 cross-version/schema-bump contract; use executable owners for volatile detail |
| Document | Scope |
|---|---|
| supersync-scenarios.md | Representative scenario-to-test routing; executable tests own behavior |
| Document | Scope |
|---|---|
| sqlite-migration.md | Current native SQLite durability rationale, landed foundation, remaining rollout gates |
| Location | Content |
|---|---|
| packages/super-sync-server/docs/architecture.md | SuperSync server-only architecture reference |
| packages/super-sync-server/ | SuperSync server implementation |
| ARCHITECTURE-DECISIONS.md | Load-bearing product/data decisions |
Retired diagram filenames remain as small forwarding stubs so historical links
continue to resolve. operation-rules.md and sqlite-migration-followup.md are
also compatibility pointers; they are not independent sources of current
behavior or status.