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.