iCloud sync so training survives one device

[sarthakagrawal927]

Setline records training to one JSON document in the app's container. That is the only copy: lose or replace the iPhone and the history is gone, and the JSON export is the only backup. Every public surface now states this plainly, which makes it the most visible gap in the product.

Outcome

Training appears on every device signed into the same iCloud account, with no account of Setline's own, no server, and no conflict UI to think about mid-workout.

Open design decision

The original plan said SwiftData + CloudKit. Having settled the domain model, that now looks like the wrong trade: it means rewriting the value-type domain (SetlineDocument and friends) into @Model reference types, which breaks the 64 core tests that operate on structs, and it fights CloudKit's all-optional / no-unique-constraint rules.

CloudKit with per-record granularity — one record per session, template and goal, keyed by ID — reaches the identical outcome while keeping the value types and their tests intact. Sessions are append-only, so they union naturally across devices rather than conflicting.

Recommendation: per-record CloudKit. Needs a decision before implementation starts.

Scope

• com.apple.developer.icloud-container-identifiers entitlement and container setup
• Per-record push and pull with a local change token; last-writer-wins on the few mutable records (templates, goals), union on append-only history
• Settings shows real iCloud state from CKAccountStatus plus a last-merge time, replacing the current copy that says sync is "being built"
• The JSON export path keeps working throughout as the escape hatch
• Migration for documents that already exist on device, with a captured fixture test

Verification

Simulator can cover the record mapping and merge logic. Two-device convergence needs real devices signed into one iCloud account and cannot be claimed from simulator alone.

[sarthakagrawal927]

Proceeding with per-record CloudKit under a stated assumption rather than blocking on the decision, since it is reversible and it is the option I recommended. If you would rather have SwiftData+CloudKit, say so and I will rework it — the merge rules below are transport-agnostic and would survive the change.

Landed: the merge core (no transport)

The part of syncing that can silently lose training is the merge, not the network. That is now built as pure, injected-clock Swift in SetlineCore/Sync/, with 16 tests, ahead of any CloudKit code:

• History is append-only and never resolves by time. Two phones that recorded different sessions end up with both. A session tombstone cannot win, so a device with a wrong clock — or one that never saw a workout — cannot erase it.
• Templates and goals are last-writer-wins, with tombstones so a delete actually propagates instead of the other device pushing the entity straight back.
• Ties are broken on payload bytes, so two devices merging the same pair reach the same answer rather than disagreeing forever.
• The active session is never synced. A workout in progress belongs to the phone in your hand; syncing it would let a second device advance or finish a set you are still doing.
• Bundled templates are not records. Shipping content should not travel through your iCloud account.
• Merging is idempotent — a settled merge stops proposing work.

One real bug this found

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

A deliberate non-change

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

Remaining

• CloudKit transport: container, zone, CKRecord mapping, change tokens, retry
• com.apple.developer.icloud-container-identifiers entitlement — needs the Apple Developer account, so it is an owner step
• Persist the ledger beside the document
• Real iCloud status in Settings from CKAccountStatus, replacing the "being built" copy
• Two-device convergence on real hardware. This cannot be claimed from simulator, so sync stays unshipped until it is verified.

The engine has no caller yet by design: it is committed with its tests so the rules can be reviewed before anything trusts them with real data.

[sarthakagrawal927]

Software half is on main via #48: per-record merge, CloudKit private-database transport, Settings status, launch/foreground reconcile, and privacy that still says sync is built but not active.

Still owner steps before this can close:

1. Create the CloudKit container iCloud.com.significanthobbies.setline on the app ID (device signing fails without it).
2. Two-device convergence on hardware signed into one iCloud account. Simulator cannot claim that.

Until those land, Settings will tell the truth about why iCloud is idle, and export remains the backup.

[sarthakagrawal927]

CloudKit container is now registered on team 8F7LXHTJZR.

Automatic signing produced a development profile (d7fefd70-…, 16 Aug 2026) that includes iCloud.com.significanthobbies.setline, and a device Debug build signed with those entitlements. The old Sign-in-with-Apple-only Setline profiles did not have iCloud; this one does.

Still blocked on hardware:

• Sarthak’s iPhone 16 Pro is paired, Developer Mode on, last seen today — currently unavailable (not on USB or network).
• Sarthak’s iPad Air is paired but last seen 5 Jul, Developer Mode off.

Plug the iPhone in (and the iPad if two-device is the claim) and the install + sync check can run.