Johannes Millan
361d0e605f
refactor(sync): rename "stale" to "superseded" across sync/operation domain
...
Includes backward compatibility: client accepts both CONFLICT_SUPERSEDED
and CONFLICT_STALE from the server, and the server keeps a deprecated
CONFLICT_STALE alias. Remove after all deployments are updated.
2026-01-30 16:59:40 +01:00
Johannes Millan
4ab86ba0fe
docs(sync): document archive-wins rule, singleton LWW, and stale op handling
...
Document 6 gaps found during documentation audit:
- Archive-wins conflict resolution rule (moveToArchive always wins
over field-level updates regardless of timestamps)
- Two-level archive resurrection prevention (ConflictResolutionService
+ bulkOperationsMetaReducer pre-scan filtering)
- Singleton entity LWW update handling (adapter vs singleton vs
unsupported storage patterns)
- Stale moveToArchive operation preservation with merged vector clocks
- Fix upload batch size from 100 to 25 in operation-rules.md and
operation-log-architecture.md
- Update meta-reducer chain from simplified 7-phase to accurate
8-phase, 15-entry structure matching meta-reducer-registry.ts
2026-01-30 16:59:40 +01:00
Johannes Millan
9f0adbb95c
docs: fix outdated file paths and types in diagrams
...
- Fix FileBasedSyncData type: remove non-existent lastSeq, add clientId
- Fix file paths: op-log/processing → op-log/apply
- Fix file paths: features/time-tracking → features/archive
- Fix file path: super-sync not supersync
- Fix vector-clock path: now in op-log/sync/
- Remove non-existent state-capture.meta-reducer.ts reference
- Remove pfapi-migration.service.ts (no longer exists)
docs: remove outdated .bak file references from diagrams
The backup file (sync-data.json.bak) is no longer created during
upload. It's only deleted as cleanup from legacy implementations.
docs: add sync comparison and simple sync flow diagrams
- Add 07-supersync-vs-file-based.md comparing the two sync approaches
- Add 08-sync-flow-explained.md with step-by-step sync explanation
- Remove consolidated unified-oplog-sync-diagrams.md
- Update diagrams README with new entries
docs(sync): reorganize diagrams into subfolder and update for unified architecture
- Create docs/sync-and-op-log/diagrams/ with topic-based diagram files
- Remove outdated PFAPI Legacy Bridge references from diagrams
- Update archive diagrams to use generic "Archive Database" naming
- Fix file paths from sync/providers/ to sync-providers/
- Update quick-reference Area 12 to show unified file-based sync
- Update README to reference new diagram locations
docs: update architecture docs to reflect PFAPI elimination
- Delete obsolete PFAPI documentation:
- docs/sync-and-op-log/pfapi-sync-persistence-architecture.md
- docs/sync-and-op-log/pfapi-sync-overview.md
- docs/plans/pfapi-elimination-status.md
- Update sync-and-op-log/README.md:
- Describe unified operation log architecture
- Document file-based sync (Part B) and server sync (Part C)
- Update file structure to reflect sync-providers location
- Update operation-log-architecture.md:
- Rewrite Part B from "Legacy Sync Bridge" to "File-Based Sync"
- Remove all PFAPI code examples and references
- Update IndexedDB structure diagram (single SUP_OPS database)
- Update architecture overview to show current provider structure
- Add notes about PFAPI elimination (January 2026)
- Mark completed implementation plans:
- replace-pfapi-with-oplog-plan.md - marked as COMPLETED
- file-based-oplog-sync-implementation-plan.md - marked as COMPLETED
Also includes fix for file-based sync gap detection to handle
snapshot replacement (when "Use Local" is chosen in conflict resolution).
2026-01-08 11:10:29 +01:00
Johannes Millan
4e49628eca
chore: clean up leftover pfapi references after refactor
...
- Remove dead test:shard:pfapi script from package.json
- Update AGENTS.md persistence layer path to op-log and sync
- Update documentation file paths in secure-storage.md,
vector-clocks.md, and quick-reference.md
2026-01-07 21:10:38 +01:00
Johannes Millan
d6dcc86ca0
refactor: reorganize operation-log files into src/app/op-log/
...
Move operation-log from src/app/core/persistence/operation-log/ to
src/app/op-log/ with improved subdirectory organization:
- core/: Types, constants, errors, entity registry
- capture/: Write path (Actions → Operations)
- operation-capture.meta-reducer.ts
- operation-capture.service.ts
- operation-log.effects.ts
- apply/: Read path (Operations → State)
- bulk-hydration.action.ts/.meta-reducer.ts
- operation-applier.service.ts
- operation-converter.util.ts
- hydration-state.service.ts
- archive-operation-handler.service.ts/.effects.ts
- store/: IndexedDB persistence
- operation-log-store.service.ts
- operation-log-hydrator.service.ts
- operation-log-compaction.service.ts
- schema-migration.service.ts
- sync/: Server sync (SuperSync)
- operation-log-sync.service.ts
- operation-log-upload.service.ts
- operation-log-download.service.ts
- conflict-resolution.service.ts
- sync-import-filter.service.ts
- vector-clock.service.ts
- operation-encryption.service.ts
- validation/: State validation
- validate-state.service.ts
- validate-operation-payload.ts
- util/: Shared utilities
- entity-key.util.ts
- client-id.provider.ts
- testing/: Integration tests and benchmarks
This reorganization:
- Places op-log at the same level as pfapi for better visibility
- Groups files by responsibility (write path vs read path)
- Makes the sync architecture more discoverable
- Improves navigation for developers new to the codebase
2025-12-27 17:52:11 +01:00
Johannes Millan
693e71deeb
docs(sync): complete quick-reference with Areas 8-12
...
Add visual summaries for remaining areas:
- Area 8: Meta-Reducers (atomic multi-entity changes)
- Area 9: Compaction (snapshot + garbage collection)
- Area 10: Bulk Application (single dispatch optimization)
- Area 11: Encryption (AES-256-GCM + Argon2id)
- Area 12: Legacy PFAPI Bridge (WebDAV/Dropbox)
Removes "Coming Soon" placeholder. All 12 areas now documented.
2025-12-27 17:10:18 +01:00
Johannes Millan
e221afe81c
docs(sync): add quick-reference.md with visual summaries
...
Create a quick reference document with ASCII diagrams summarizing:
- Area 1: Write Path
- Area 2: Read Path (Hydration)
- Area 3: Server Sync (SuperSync)
- Area 4: Conflict Detection
- Area 5: Conflict Resolution (LWW)
- Area 6: SYNC_IMPORT Filtering
- Area 7: Archive Handling
Includes decision tables, key invariants, and file references.
Areas 8-12 placeholders for future additions.
2025-12-27 16:42:38 +01:00
