Configurable CloudKit Conflict Resolution Strategy

[lukaskubanek]

SQLiteData in its initial version (1.2.0) handles conflicts arising from CloudKit sync using a per-field last-write-wins (LWW) strategy. The docs mention the possibility of supporting custom conflict resolution in the future. I’m not sure about your upcoming plans or general timeline, but I’d like to kick off a discussion about how this could be approached.

While the per-field LWW strategy serves as a solid default (kudos for going the extra mile compared to SwiftData!), it would be helpful to be able to hook into the conflict resolution with a custom strategy.

Granularity

The first question is what granularity conflicts should be handled at? In other words, what should be considered an atomic unit from the conflict’s point of view? This could be a field, a row, or the entire database. While all levels could be useful depending on the app’s logic and data integrity requirements, I’d argue that handling conflicts at the row level is the right approach, as this is how CloudKit itself sees and reports conflicts. Furthermore, it’s in line with the default strategy already implemented in SQLiteData.

2-Way vs. 3-Way Merge

This implies there could be a hook configured per table via the SyncEngine, executed whenever a conflict is detected, with the hook producing a merged row using client-provided logic. The hook would receive at least the two conflicting versions: client and server. While such a 2-way merge already enables a lot of flexibility, it would be even more useful to include the common ancestor version as well, allowing for proper 3-way merges.

The tricky part is that CloudKit doesn’t provide the ancestor version. The ancestorRecord found in the userInfo of a serverRecordChanged CKError only includes system fields, while the actual data fields are not populated. Turns out, the fields of the ancestor record get populated after all. See this comment for more details.

Things get even more complicated, because these server rejections are not the only way conflicts can arise. There’s also the inverse scenario: a local row is modified, but before it’s synced with the server, a remote change is received for that same row. (I’m not sure whether this case is already handled in SQLiteData using the default strategy or whether one of the versions gets overwritten by the other.)

Long story short, to support ancestor-based conflict resolution, the ancestor version would need to be tracked locally for each row with pending changes and discarded once the row is successfully synced.

It might remind you of the Git-like branching model from Forked, but in SQLiteData’s case, it’s not necessary to keep track of the entire history, as this is taken care of by CloudKit. The ancestor would only need to be stored temporarily for the purpose of conflict resolution.

Table Types vs. Raw CKRecords

Assuming the conflict resolution hook receives the ancestor, client, and server versions, the next question is whether it should operate on the decoded Table type or on the raw CKRecord.

My initial thought was that decoding could cause issues when clients run different schema versions. But as mentioned in your recent episode, SQLiteData preserves unknown fields and reapplies them after migrating the schema. So, having the conflict resolution logic operate on the decoded Table type should be safe and shouldn’t differ from any other update to the row.

On the other hand, working with raw CKRecords would allow for more flexibility, but it could feel too detached, as one might want to express the merge logic in terms of the database schema and model types.

Hook Registration

There are other CloudKit abstraction frameworks out there that attach a static conflict resolution method to the model type, which would correspond to SynchronizableTable in SQLiteData. But I don’t think this is a great idea, as it would tie all tables to a specific conflict resolution strategy. A better approach could be a per-table registry at the SyncEngine level, allowing only selected tables to participate. (This could be done in the initializer or the recently introduced SyncEngineDelegate). The consequence is that SQLiteData would only need to track ancestor records for those opted-in tables.

@mbrandonw @stephencelis Think of this as an idea dump after briefly exploring the initial version of your library with CloudKit support. I’d love to hear whether this aligns with your vision for custom conflict resolution, or whether you have something else in mind.

[stephencelis]

@lukaskubanek Thanks for the discussion and for thoroughly exploring the library as it exists so far 😄

We are definitely open to configurable conflict resolution. We just felt that per-field last-wins works for 99% of the use cases out there (and is an improvement over SwiftData's all-fields last-wins strategy).

If you'd like to explore contributing support for such a feature, we'd love to work with you to help land it!

This is probably the place that would need to be instrumented to support customization:

sqlite-data/Sources/SQLiteData/CloudKit/SyncEngine.swift

Lines 1516 to 1519 in 8874760

	case .serverRecordChanged:
	guard let serverRecord = error.serverRecord else { continue }
	await upsertFromServerRecord(serverRecord)
	newPendingRecordZoneChanges.append(.saveRecord(failedRecord.recordID))

And leveraging SyncEngineDelegate, as you suggest, is probably a good place to start.

The tricky part is that CloudKit doesn’t provide the ancestor version. The ancestorRecord found in the userInfo of a serverRecordChanged CKError only includes system fields, while the actual data fields are not populated.

The docs don't seem to suggest that's the case, so I did a quick test and ancestorRecord does seem to have all the fields, not just the system ones:

(lldb) po error.ancestorRecord!
<CKRecord: 0x101050590; recordType=reminders, recordID=6c601d4c-afca-4057-9b6b-68efb09883f5:reminders:(co.pointfree.SQLiteData.defaultZone:__defaultOwner__), recordChangeTag=42, parent=<CKReference: 0x6000003c6920; recordID=<CKRecordID: 0x6000003c6940; recordName=d0b9ddd3-1d85-412d-b3e6-990c8818e557:remindersLists, zoneID=co.pointfree.SQLiteData.defaultZone:__defaultOwner__>>, encryptedValues={
    dueDate = "<CKEncryptedDate: 0x6000003c60c0; length=11>";
    id = "<CKEncryptedString: 0x6000003cd220; length=38>";
    isFlagged = "<CKEncryptedLongLong: 0x6000003c66c0; length=2>";
    notes = "<CKEncryptedString: 0x6000003c65e0; length=2>";
    position = "<CKEncryptedLongLong: 0x6000003c6220; length=2>";
    remindersListID = "<CKEncryptedString: 0x6000003c6660; length=38>";
    "sqlitedata_icloud_userModificationTime" = "<CKEncryptedLongLong: 0x6000003c6740; length=10>";
    "sqlitedata_icloud_userModificationTime_dueDate" = "<CKEncryptedLongLong: 0x6000003c5b40; length=10>";
    "sqlitedata_icloud_userModificationTime_id" = "<CKEncryptedLongLong: 0x6000003c6700; length=10>";
    "sqlitedata_icloud_userModificationTime_isFlagged" = "<CKEncryptedLongLong: 0x6000003c61a0; length=10>";
    "sqlitedata_icloud_userModificationTime_notes" = "<CKEncryptedLongLong: 0x6000003c6680; length=10>";
    "sqlitedata_icloud_userModificationTime_position" = "<CKEncryptedLongLong: 0x6000003c6620; length=10>";
    "sqlitedata_icloud_userModificationTime_remindersListID" = "<CKEncryptedLongLong: 0x6000003c6580; length=10>";
    "sqlitedata_icloud_userModificationTime_status" = "<CKEncryptedLongLong: 0x6000003c6780; length=10>";
    "sqlitedata_icloud_userModificationTime_title" = "<CKEncryptedLongLong: 0x6000003c6120; length=10>";
    status = "<CKEncryptedLongLong: 0x6000003c67c0; length=2>";
    title = "<CKEncryptedString: 0x6000003c65c0; length=18>";
}>

So it looks like we have all the necessary data to handle a 3-way merge today. Let us know if you have any questions along the way!

[lukaskubanek]

We are definitely open to configurable conflict resolution. […] If you'd like to explore contributing support for such a feature, we'd love to work with you to help land it!

Great! I’ll have somewhat limited availability and I’m not sure about my skill level, but I’d love to give it a try.

We just felt that per-field last-wins works for 99% of the use cases out there (and is an improvement over SwiftData's all-fields last-wins strategy).

I think it really depends on the app type. Apps like Reminders, where most fields are independent and unlikely to be edited concurrently, are a good fit. However, for more collaborative apps (leveraging sharing between users), offline-first apps, or notes apps, silently losing data would be a bummer. Ideally, the framework should give developers flexibility over conflict resolution. Yet another reason why SQLiteData could give you this power while SwiftData (or Core Data) couldn’t due to how opaquely it’s designed.

This is probably the place that would need to be instrumented to support customization

I’ve started looking through the codebase and have reported two bugs that are both somewhat related to upserting local rows from server records.

The docs don’t seem to suggest [the that ancestor record doesn’t have populated fields], so I did a quick test and ancestorRecord does seem to have all the fields, not just the system ones

That’s very surprising! You’re right that neither the CloudKit documentation nor the WWDC 2015 session “715 - CloudKit Tips and Tricks” (which includes a section on conflict handling) mention whether the ancestor record should include all fields. I based my statement on my own observations, as in my tests, the ancestor record didn’t contain any fields. You can see that in the snippet below (the itemsData field is only present in the client and server records):

CLICK TO SHOW DEBUGGER OUTPUT

(lldb) po (failedRecordSave.error as NSError)
<CKError 0x600000c98600: "Server Record Changed" (14/2004); server message = "client oplock error updating record"; clientEtag = qd; serverEtag = qf; op = 467776ED2A9A98FA; uuid = A5F23927-60BE-4435-956D-2644EF158B08; container ID = "iCloud.eu.structuredpath.CloudKitStore.Example">

(lldb) po failedRecordSave.error.ancestorRecord!
CKRecord: 0x101d1f230; recordType=ListContent, recordID=7B048B5C-5403-48A7-8DEF-3DFF959A10AB:(eu.structuredpath.CloudKitStore.zone:__defaultOwner__), recordChangeTag=qd, parent=<CKReference: 0x600000335120; recordID=<CKRecordID: 0x600000334cc0; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>>
{
	creatorUserRecordID -> CKRecordID: 0x6000003136a0; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	lastModifiedUserRecordID -> CKRecordID: 0x600000334b00; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	creationDate -> 2024-02-13 07:08:48 +0000
	modificationDate -> 2025-10-24 00:42:00 +0000
	modifiedByDevice -> iPhone 16 (iOS 26.1)
	parent-> CKReference: 0x600000335120; recordID=<CKRecordID: 0x600000334cc0; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>
}

(lldb) po failedRecordSave.error.clientRecord!
CKRecord: 0x102d4ff90; recordType=ListContent, recordID=7B048B5C-5403-48A7-8DEF-3DFF959A10AB:(eu.structuredpath.CloudKitStore.zone:__defaultOwner__), recordChangeTag=qd, parent=<CKReference: 0x600000335120; recordID=<CKRecordID: 0x600000334cc0; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>, values={
    itemsData = "{ length=319, sha256=568c31d74dca13de2a775817641499cecf44e4d30bb1eacad498e1938651b45d }";
}>
{
	creatorUserRecordID -> CKRecordID: 0x6000003136a0; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	lastModifiedUserRecordID -> CKRecordID: 0x600000334b00; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	creationDate -> 2024-02-13 07:08:48 +0000
	modificationDate -> 2025-10-24 00:42:00 +0000
	modifiedByDevice -> iPhone 16 (iOS 26.1)
	parent-> CKReference: 0x600000335120; recordID=<CKRecordID: 0x600000334cc0; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>
	itemsData (modified) -> 5b7b226964223a2235303938374636382d384235342d343141422d413746342d314331393238394134343241222c227469746c65223a225375676172227d2c7b226964223a2237393345324137442d453532332d344537392d424245432d313039333545423641303333222c227469746c65223a22427574746572227d2c7b226964223a2235323534433143422d424236352d343131332d424131422d363237423737433641343030222c227469746c65223a2241766f6361646f31227d2c7b226964223a2241433034424241352d393342422d343046332d383732392d344633343739394334444243222c227469746c65223a225761746572227d2c7b226964223a2237344136363031352d444531332d344343302d424433322d334635304238303733363943222c227469746c65223a22537061676865747469227d5d
}

(lldb) po failedRecordSave.error.serverRecord!
CKRecord: 0x102d2ba30; recordType=ListContent, recordID=7B048B5C-5403-48A7-8DEF-3DFF959A10AB:(eu.structuredpath.CloudKitStore.zone:__defaultOwner__), recordChangeTag=qf, parent=<CKReference: 0x600000334ca0; recordID=<CKRecordID: 0x600000336c00; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>, values={
    itemsData = "{ length=319, sha256=9d3248c73b660582fefd486238d710750b1a795cd716ae5cd3726bf985dbe479 }";
}>
{
	creatorUserRecordID -> CKRecordID: 0x600000337a20; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	lastModifiedUserRecordID -> CKRecordID: 0x600000336400; recordName=__defaultOwner__, zoneID=_defaultZone:__defaultOwner__
	creationDate -> 2024-02-13 07:08:48 +0000
	modificationDate -> 2025-10-24 00:48:02 +0000
	modifiedByDevice -> iPhone Air (iOS 26.1)
	parent-> CKReference: 0x600000334ca0; recordID=<CKRecordID: 0x600000336c00; recordName=BA4A403F-11C8-43B5-AB1A-81BD6AD3ACD8, zoneID=eu.structuredpath.CloudKitStore.zone:__defaultOwner__>
	itemsData -> 5b7b226964223a2235303938374636382d384235342d343141422d413746342d314331393238394134343241222c227469746c65223a225375676172227d2c7b226964223a2237393345324137442d453532332d344537392d424245432d313039333545423641303333222c227469746c65223a22427574746572227d2c7b226964223a2235323534433143422d424236352d343131332d424131422d363237423737433641343030222c227469746c65223a2241766f6361646f32227d2c7b226964223a2241433034424241352d393342422d343046332d383732392d344633343739394334444243222c227469746c65223a225761746572227d2c7b226964223a2237344136363031352d444531332d344343302d424433322d334635304238303733363943222c227469746c65223a22537061676865747469227d5d
}

That said, I can confirm that SQLiteData does populate all fields of the ancestor record. The only difference I’ve noticed is that SQLiteData defaults to encrypted fields, whereas my test project uses unencrypted fields. Not sure if this is the reason, as it’s not documented, but if so, then it’d be unreliable should SQLiteData add support for unencrypted fields.

@stephencelis Could you also comment on this part from my original post?

Things get even more complicated, because these server rejections are not the only way conflicts can arise. There’s also the inverse scenario: a local row is modified, but before it’s synced with the server, a remote change is received for that same row. (I’m not sure whether this case is already handled in SQLiteData using the default strategy or whether one of the versions gets overwritten by the other.)

I haven’t yet inspected this case in detail, but can you confirm that it’s handled by the second upsert called from handleFetchedRecordZoneChanges(…)?

[mbrandonw]

You can see that in the snippet below (the itemsData field is only present in the client and server records):

Is itemsData an BLOB field of data? Perhaps data blobs are not included in ancestor records for some reason. Could you add a non-blob field to your CKRecord to see if then it starts coming back in ancestor records? If it still does not then can you add some fields to encryptedValues to see if then those fields start coming back in ancestor records.

[lukaskubanek]

@stephencelis @mbrandonw OK, I think I’ve found the cause of the ancestor record’s fields not being populated.

In my implementation, when uploading changes to CloudKit, I create a CKRecord from the persisted system fields serialized via CKRecord.encodeSystemFields(with:) and restored via CKRecord.init(coder:), then fill in the fields from an in-memory representation. According to the docs, this should be enough to maintain lineage of the record. And while it’s the case (unlike starting with a fresh CKRecord), it results in the ancestor record in a serverRecordChanged error having no populated fields.

On the other hand, when I create a full-fledged CKRecord that was serialized with CKRecord.encode(with:) and apply the changes to that, the ancestor record’s fields become populated.

And since SQLiteData applies values fetched from the database to a CKRecord created from SyncMetadata._lastKnownServerRecordAllFields (which includes all fields) rather than SyncMetadata.lastKnownServerRecord (system fields only), the ancestor record’s fields get populated.

This means it’s not related to the data type or encryption. It’s based on how the CKRecord sent to CloudKit is constructed.

That said, the ancestor record seems to effectively match SyncMetadata._lastKnownServerRecordAllFields anyway. And because that record is likely required even when upserting changes coming from the server without hitting serverRecordChanged (the opposite scenario I mentioned above), the ancestor might be uniformly fetched from the metadatabase for both scenarios. Any thoughts on this approach?