iCloud sync: the merge core, no transport yet

[sarthakagrawal927]

Stacked on #40 so its diff shows only the sync work. Draft because sync is not usable yet and must not be reported as working.

Part of #44.

Why the merge first, and alone

The merge is the only part of syncing that can silently destroy recorded training. So it is built and tested before any CloudKit code exists — pure functions with an injected clock, reviewable without a container, a network, or a device.

Taking per-record CloudKit over the originally planned SwiftData+CloudKit. That is stated as an assumption on #44 rather than a settled decision; the rules here are transport-agnostic and survive the change if you prefer SwiftData. SwiftData would mean rewriting the value-type domain into @Model reference types and breaking the 64 core tests, and a whole-document copy forces a person to choose between two versions of their training whenever two devices both wrote.

The rules, each with a test

Rule	Why
History is append-only, never resolves by time	Two phones with different sessions end up with both. A wrong clock cannot lose a workout.
A session tombstone cannot win	Nothing in the app deletes a workout, so such a record is corruption or a stale device.
Templates and goals are last-writer-wins, with tombstones	Without tombstones a delete never propagates — the other device pushes the entity straight back.
Ties break on payload bytes	Two devices merging the same pair must reach the same answer, not disagree forever.
The active session is never synced	A workout in progress belongs to the phone in your hand.
Bundled templates are not records	Shipping content should not travel through somebody's iCloud account.
Merging a settled result proposes no work	Idempotence, so sync does not churn.

One real defect this caught

The round-trip test failed: .iso8601 truncates dates to whole seconds, so a record did not decode back to the value it was encoded from. Left in, every record would look freshly edited on each trip, and two edits inside one second would tie on timestamp and fall through to the arbitrary tie-break. Sync payloads now encode dates exactly; the export keeps ISO 8601, which is right for a file a person may open.

A deliberate non-change

WorkoutTemplate and ExerciseGoal gained no updatedAt field. That puts sync bookkeeping inside the training model, where every mutation site must maintain it and will be wrong the first time one forgets. A SyncLedger fingerprints the encoded payload instead, which cannot be forgotten.

Verification

• 80 unit tests (64 existing + 16 new) and 11 UI tests pass; release build succeeds
• Coverage 84.3236%, up from 84.1529% — the new code is covered, not just added
• Duplication zero; complexity unchanged at 9 violations, max CCN 15

Not done, and not claimed

Transport (container, zone, CKRecord mapping, change tokens, retry), the com.apple.developer.icloud-container-identifiers entitlement — which needs the Apple Developer account and so is an owner step — ledger persistence, and real CKAccountStatus in Settings. Settings still says sync is not active, which is still true.

Two-device convergence cannot be verified from a simulator, so sync stays unshipped until it is checked on hardware.

🤖 Generated with Claude Code