feat: expose recovery actions only for recoverable SyncEngine.SharingErrors

[MojtabaHs]

Summary

Expose a public recovery action for SyncEngine.SharingError without making the error type itself public.

This allows callers to determine when a sharing operation can be recovered by starting the sync engine or sending pending changes and retrying.

Usage

For example, a sharing operation can use the recovery action to synchronize the engine and retry when possible:

do {
  sharedRecord = try await syncEngine.share(record: myRecord) { ... }
} catch let error as SyncEngine.RecoverableSharingError {
  switch error.recoveryAction {
  case .sendChangesAndRetry: try await syncEngine.sendChanges()
  case .startAndRetry: try await syncEngine.start()
  case .none: throw error // Re-throws unrecoverable errors
  }
  sharedRecord = try await syncEngine.share(record: myRecord) { ... }
}

Motivation

Following the recent thread on the sqlite-data Slack channel, it turns out that SharingError is currently private, but some of its errors provide actionable recovery guidance in their debugDescription.

For example, .recordMetadataNotFound explicitly suggests calling sendChanges() to force synchronization:

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

Lines 138 to 143 in f6bd67a

	reason: .recordMetadataNotFound,
	debugDescription: """
	No sync metadata found for record. Has the record been saved to the database \
	and synchronized to iCloud? Invoke 'SyncEngine.sendChanges()' to force \
	synchronization.
	"""

Without a public recovery API, callers cannot reliably identify this condition and perform the suggested recovery.

This change exposes the recovery contract while keeping the underlying SharingError and its internal reasons private.

Changes

• Add SyncEngine.SharingErrorRecoveryAction.
• Add SyncEngine.RecoverableSharingError to expose recovery actions without exposing SharingError.
• Provide .startAndRetry for .syncEngineNotRunning.
• Provide .sendChangesAndRetry for .recordMetadataNotFound.
• Add tests covering the exposed recovery actions following the existing testing pattern and using inline snapshots.

[ArchimedesTrajano]

Thank you! I think this can be useful until the error is exposed, and potentially even longer. This covers my needs.

[stephencelis]

@MojtabaHs Thanks for exploring! While we definitely want to do this, it's something we also want to take some care to design properly, either determining a finite set of enum cases that is fully extensible in the future for our needs, or losing the closed enum entirely so that we can support more kinds of errors in the future. Going to close this for now but we are tracking the issue internally. Also either of you can open a public issue if you want it tracked more publicly.

[ArchimedesTrajano]

Is it possible to merge the latest version into this PR?

[MojtabaHs]

@ArchimedesTrajano If you mean my branch, I did. But you should follow Brandon’s advice, or just wait and follow what Stephen suggested.

Also, please fork it and maintain the code yourself. I don’t plan to keep this around.