refactor(sync-core): drop shared-schema vector-clock compat re-export anda app enum (#8441)

* feat(sync-core): drop shared-schema vector-clock compat re-export and app enum

- Remove the shared-schema → sync-core compatibility re-export of
vector-clock types/functions; retarget app files
(vector-clock.ts,operation-log.const.ts) and the server (sync.types.ts)
to import from @sp/sync-core directly
- Add @sp/sync-core to super-sync-server/package.json deps (it was
load-bearing through the re-export)
- Convert VectorClockComparison from a bare type to an as const object +
derived type in sync-core,drop the app-side enum copy and the as cast
- Update spec imports and pa ckage-boundaries.md

* docs: remove stale shared-schema vector-clock references

- Update comments in vector-clocks.md, client vector-clock.ts, and
  server sync.types.ts to reference @sp/sync-core directly
- Remove @sp/sync-core dependency from shared-schema/package.json
- Regenerate package-lock.json to reflect the removed edge

* docs(sync): fix orphaned VectorClockComparison comment

The comment block describing VectorClockComparison was left dangling
above no declaration after the app-side enum was removed, and still
claimed 'Uses enum for client-side ergonomics'. Move it above the
re-export it documents and correct the wording.

---------

Co-authored-by: Johannes Millan <johannes.millan@gmail.com>
This commit is contained in:
Mohamed Abdeltawab 2026-06-17 17:21:26 +03:00 committed by GitHub
parent 898436e3da
commit c2bf7b26a0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 54 additions and 624 deletions

View file

@ -19,8 +19,9 @@ src/app
src/app
-> @sp/sync-core
packages/shared-schema
packages/super-sync-server
-> @sp/sync-core
-> @sp/shared-schema
```
Rules:
@ -33,16 +34,10 @@ Rules:
- The app may import both packages and is responsible for Angular dependency
injection, NgRx, Electron/Capacitor bridges, config UI, OAuth routing, and
Super Productivity-specific model wiring.
- `packages/shared-schema` depends on `@sp/sync-core` only for compatibility
re-exports of generic vector-clock algorithms.
The `packages/shared-schema -> @sp/sync-core` edge is deliberate compatibility
coupling. Vector-clock compare/merge/prune algorithms moved to `@sp/sync-core`
so sync-core, client wrappers, and server/shared consumers use one
implementation. `packages/shared-schema` re-exports those algorithms to preserve
legacy import paths while consumers migrate; do not add new sync-engine logic to
`@sp/shared-schema`, and remove the compatibility edge once no consumers need
it.
- `packages/shared-schema` owns schema contracts and validators shared between
app and server. It has no dependency on `@sp/sync-core`.
- `packages/super-sync-server` depends on both `@sp/shared-schema` (HTTP contract
types and validation schemas) and `@sp/sync-core` (vector-clock algorithms).
## Ownership

View file

@ -26,7 +26,7 @@ At 6-char client IDs, a 20-entry clock is ~333 bytes — negligible bandwidth. A
## 2. Core Operations
Three operations — compare, merge, and prune (`limitVectorClockSize`) — are implemented in the generic sync-core package (`packages/sync-core/src/vector-clock.ts`), used by both client and server. `packages/shared-schema/src/vector-clock.ts` re-exports those algorithms for existing shared-schema import paths. Two operations — initialize and increment — are client-only (`src/app/core/util/vector-clock.ts`), which also wraps the shared operations with null-handling and logging.
Three operations — compare, merge, and prune (`limitVectorClockSize`) — are implemented in the generic sync-core package (`packages/sync-core/src/vector-clock.ts`), used by both client and server. Two operations — initialize and increment — are client-only (`src/app/core/util/vector-clock.ts`), which also wraps the shared operations with null-handling and logging.
### Create
@ -142,7 +142,7 @@ Otherwise:
3. Return clock with exactly MAX entries
```
Implemented in `packages/sync-core/src/vector-clock.ts` and re-exported from `packages/shared-schema/src/vector-clock.ts`. The client wrapper in `src/app/core/util/vector-clock.ts` adds logging and passes `[currentClientId]` as the preserve list.
Implemented in `packages/sync-core/src/vector-clock.ts`. The client wrapper in `src/app/core/util/vector-clock.ts` adds logging and passes `[currentClientId]` as the preserve list.
### When Pruning Happens (Exhaustive List)
@ -345,7 +345,7 @@ Rules that must hold for the system to be correct. Use these to verify implement
3. **Client does NOT prune during conflict resolution.** `SupersededOperationResolverService` sends full merged clocks; the server prunes after accepting.
4. **`compareVectorClocks` produces identical results on client and server.** Both import from `@sp/shared-schema`. The client wrapper only adds null handling.
4. **`compareVectorClocks` produces identical results on client and server.** Both import from `@sp/sync-core`. The client wrapper only adds null handling.
5. **Full-state ops skip conflict detection on server.** `detectConflict()` returns `{ hasConflict: false }` for SYNC_IMPORT, BACKUP_IMPORT, and REPAIR.
@ -362,7 +362,7 @@ Rules that must hold for the system to be correct. Use these to verify implement
| Concept | File(s) |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Core algorithms (compare, merge, prune) | `packages/sync-core/src/vector-clock.ts` |
| Compatibility re-export for existing shared-schema imports | `packages/shared-schema/src/vector-clock.ts` |
| Compatibility re-export for existing shared-schema imports | (removed — imports now target `@sp/sync-core` directly) |
| Client wrappers (null handling, logging, validation) | `src/app/core/util/vector-clock.ts` |
| Global clock management, entity frontier | `src/app/op-log/sync/vector-clock.service.ts` |
| Operation capture (no pruning, atomic clock update) | `src/app/op-log/capture/operation-log.effects.ts` |