Add operation classification and batch sync result tracking

Sources/MistKit/Service/BatchSyncResult.swift

@@ -0,0 +1,142 @@
+//
+//  BatchSyncResult.swift
+//  MistKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import Foundation
+
+/// Categorized result of a tracked `modifyRecords(_:classification:atomic:)` call.
+///
+/// Returned by `CloudKitService.modifyRecords(_:classification:atomic:)`,
+/// this struct partitions the records returned by CloudKit into four groups
+/// based on the supplied `OperationClassification`:
+///
+/// - `created`: results whose record name was classified as a create
+/// - `updated`: results whose record name was classified as an update
+/// - `failed`: results that came back as errors (`RecordInfo.isError == true`)
+/// - `unclassified`: successful results whose record name was in neither
+///   the creates nor updates sets — for example, anonymous creates where
+///   CloudKit assigned the record name server-side, or records whose name
+///   was not included in the classification
+///
+/// Use the `*Count` properties to drive sync summaries and audit logs.
+public struct BatchSyncResult: Sendable {
+  /// Records classified as newly created.
+  public let created: [RecordInfo]
+
+  /// Records classified as updates to existing records.
+  public let updated: [RecordInfo]
+
+  /// Records that came back as errors.
+  public let failed: [RecordInfo]
+
+  /// Successful records that could not be classified as either a create or update.
+  ///
+  /// Typically contains anonymous creates where CloudKit assigned the record
+  /// name server-side, since their names won't appear in either set of the
+  /// supplied `OperationClassification`.
+  public let unclassified: [RecordInfo]
+
+  /// Number of records classified as created.
+  public var createdCount: Int { created.count }
+
+  /// Number of records classified as updated.
+  public var updatedCount: Int { updated.count }
+
+  /// Number of records that returned an error.
+  public var failedCount: Int { failed.count }
+
+  /// Number of successful records that could not be classified.
+  public var unclassifiedCount: Int { unclassified.count }
+
+  /// Total number of records returned by CloudKit, across all categories.
+  public var totalCount: Int {
+    created.count + updated.count + failed.count + unclassified.count
+  }
+
+  /// Number of records that completed successfully (created + updated + unclassified).
+  public var succeededCount: Int {
+    created.count + updated.count + unclassified.count
+  }
+
+  /// Build a `BatchSyncResult` directly from category arrays.
+  ///
+  /// Prefer `init(records:classification:)` in production code; this
+  /// initializer is intended for tests and manual construction.
+  public init(
+    created: [RecordInfo],
+    updated: [RecordInfo],
+    failed: [RecordInfo],
+    unclassified: [RecordInfo] = []
+  ) {
+    self.created = created
+    self.updated = updated
+    self.failed = failed
+    self.unclassified = unclassified
+  }
+
+  /// Partition a flat array of `RecordInfo` results into a `BatchSyncResult`
+  /// using a pre-computed classification.
+  ///
+  /// Each record is sorted as follows:
+  /// 1. If `record.isError` is `true`, it is added to `failed`.
+  /// 2. Else if `record.recordName` is in `classification.creates`, it is added
+  ///    to `created`.
+  /// 3. Else if `record.recordName` is in `classification.updates`, it is added
+  ///    to `updated`.
+  /// 4. Otherwise it is added to `unclassified`.
+  ///
+  /// - Parameters:
+  ///   - records: The records returned by `modifyRecords`.
+  ///   - classification: The classification used to partition the records.
+  public init(
+    records: [RecordInfo],
+    classification: OperationClassification
+  ) {
+    var created: [RecordInfo] = []
+    var updated: [RecordInfo] = []
+    var failed: [RecordInfo] = []
+    var unclassified: [RecordInfo] = []
+
+    for record in records {
+      if record.isError {
+        failed.append(record)
+      } else if classification.creates.contains(record.recordName) {
+        created.append(record)
+      } else if classification.updates.contains(record.recordName) {
+        updated.append(record)
+      } else {
+        unclassified.append(record)
+      }
+    }
+
+    self.created = created
+    self.updated = updated
+    self.failed = failed
+    self.unclassified = unclassified
+  }
+}

Sources/MistKit/Service/CloudKitService+Classification.swift

@@ -0,0 +1,119 @@
+//
+//  CloudKitService+Classification.swift
+//  MistKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import Foundation
+
+/// Helpers for tracking creates vs updates in `modifyRecords` responses.
+///
+/// CloudKit's `/records/modify` endpoint does not include any indicator of
+/// whether each operation produced a newly created record or updated an
+/// existing one. The pattern in this extension implements the documented
+/// pre-fetch + classify workaround:
+///
+/// 1. Call `fetchExistingRecordNames(recordType:)` to discover which records
+///    already exist.
+/// 2. Build an `OperationClassification` from the proposed operations and the
+///    existing names.
+/// 3. Call `modifyRecords(_:classification:atomic:)` to perform the modify and
+///    receive a `BatchSyncResult` with creates/updates/failures already
+///    partitioned.
+@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *)
+extension CloudKitService {
+  /// Fetch the set of record names that already exist for a record type.
+  ///
+  /// Used as the first step of the pre-fetch + classify pattern for tracking
+  /// creates vs updates in batch modify operations. Internally this calls
+  /// `queryRecords(recordType:limit:)` and projects the results down to a
+  /// `Set<String>` of record names.
+  ///
+  /// - Important: This issues a single `queryRecords` call. CloudKit caps a
+  ///   single response at 200 records, so for larger record types you must
+  ///   paginate at the call site or use a custom query.
+  ///
+  /// - Parameters:
+  ///   - recordType: The CloudKit record type to scan.
+  ///   - limit: Optional maximum number of records to fetch (1-200). Defaults
+  ///     to CloudKit's per-request maximum.
+  /// - Returns: Set of existing record names.
+  /// - Throws: `CloudKitError` if the underlying query fails.
+  public func fetchExistingRecordNames(
+    recordType: String,
+    limit: Int? = nil
+  ) async throws(CloudKitError) -> Set<String> {
+    // Pass `limit:` explicitly so overload resolution picks the typed-throws
+    // variant of `queryRecords` rather than the 1-param RecordManaging-
+    // conforming overload (which has untyped throws).
+    let records = try await queryRecords(
+      recordType: recordType,
+      limit: limit ?? Self.maxRecordsPerRequest
+    )
+    return Set(records.map(\.recordName))
+  }
+
+  /// Modify CloudKit records and partition the response into creates,
+  /// updates, failures, and unclassified records.
+  ///
+  /// This overload calls `modifyRecords(_:atomic:)` internally and then
+  /// uses the supplied `OperationClassification` to attribute each returned
+  /// `RecordInfo` to a category. It does not issue any extra CloudKit
+  /// requests beyond the modify itself.
+  ///
+  /// ## Example
+  /// ```swift
+  /// let existing = try await service.fetchExistingRecordNames(recordType: "Article")
+  /// let classification = OperationClassification(
+  ///   operations: operations,
+  ///   existingRecordNames: existing
+  /// )
+  /// let result = try await service.modifyRecords(
+  ///   operations,
+  ///   classification: classification
+  /// )
+  /// print("Created: \(result.createdCount)")
+  /// print("Updated: \(result.updatedCount)")
+  /// print("Failed:  \(result.failedCount)")
+  /// ```
+  ///
+  /// - Parameters:
+  ///   - operations: Record operations to perform.
+  ///   - classification: Pre-computed classification of operations as creates
+  ///     vs updates, typically from `fetchExistingRecordNames(recordType:)`.
+  ///   - atomic: When `true`, the entire batch fails if any single operation
+  ///     fails (default: `false`).
+  /// - Returns: A `BatchSyncResult` partitioning the response.
+  /// - Throws: `CloudKitError` if the modify request fails.
+  public func modifyRecords(
+    _ operations: [RecordOperation],
+    classification: OperationClassification,
+    atomic: Bool = false
+  ) async throws(CloudKitError) -> BatchSyncResult {
+    let records = try await modifyRecords(operations, atomic: atomic)
+    return BatchSyncResult(records: records, classification: classification)
+  }
+}

Sources/MistKit/Service/CloudKitService.swift

@@ -41,6 +41,9 @@ import OpenAPIRuntime
 /// Service for interacting with CloudKit Web Services
 @available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *)
 public struct CloudKitService: Sendable {
+  /// CloudKit's maximum number of records returned per query/modify request.
+  internal static let maxRecordsPerRequest: Int = 200
+
   /// The CloudKit container identifier
   public let containerIdentifier: String
   /// The API token for authentication

Sources/MistKit/Service/OperationClassification.swift

@@ -0,0 +1,120 @@
+//
+//  OperationClassification.swift
+//  MistKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2026 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the "Software"), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import Foundation
+
+/// Classifies CloudKit record operations as creates or updates.
+///
+/// CloudKit's `/records/modify` endpoint does not indicate in its response
+/// whether each operation resulted in a newly-created record or an update to
+/// an existing one. The proven workaround is to query the existing record
+/// names for a record type before issuing the modify, then partition each
+/// proposed operation by whether its record name was already present.
+///
+/// `OperationClassification` captures the result of that partitioning so that
+/// `CloudKitService.modifyRecords(_:classification:atomic:)` can attribute
+/// each returned `RecordInfo` to a create or an update.
+///
+/// ## Example
+/// ```swift
+/// let existing = try await service.fetchExistingRecordNames(recordType: "Article")
+/// let classification = OperationClassification(
+///   operations: operations,
+///   existingRecordNames: existing
+/// )
+/// let result = try await service.modifyRecords(
+///   operations,
+///   classification: classification
+/// )
+/// print("Created: \(result.createdCount), Updated: \(result.updatedCount)")
+/// ```
+public struct OperationClassification: Sendable, Equatable {
+  /// Record names that are expected to be created (not present in CloudKit).
+  public let creates: Set<String>
+
+  /// Record names that are expected to be updated (already present in CloudKit).
+  public let updates: Set<String>
+
+  /// Build a classification by comparing proposed record names against existing ones.
+  ///
+  /// Operations whose record name is in `existingRecordNames` are classified as
+  /// updates; the rest are classified as creates. Duplicate names in
+  /// `proposedRecordNames` are folded into the same set entry.
+  ///
+  /// - Parameters:
+  ///   - proposedRecordNames: Record names that will be sent to CloudKit.
+  ///   - existingRecordNames: Record names already present in CloudKit
+  ///     (typically obtained via `fetchExistingRecordNames(recordType:)`).
+  public init(
+    proposedRecordNames: [String],
+    existingRecordNames: Set<String>
+  ) {
+    var creates = Set<String>()
+    var updates = Set<String>()
+
+    for recordName in proposedRecordNames {
+      if existingRecordNames.contains(recordName) {
+        updates.insert(recordName)
+      } else {
+        creates.insert(recordName)
+      }
+    }
+
+    self.creates = creates
+    self.updates = updates
+  }
+
+  /// Build a classification directly from a sequence of `RecordOperation` values.
+  ///
+  /// Operations without a `recordName` (anonymous creates where CloudKit will
+  /// assign the name) are skipped — they cannot be matched against existing
+  /// names by definition.
+  ///
+  /// - Parameters:
+  ///   - operations: The record operations that will be sent to CloudKit.
+  ///   - existingRecordNames: Record names already present in CloudKit.
+  public init(
+    operations: [RecordOperation],
+    existingRecordNames: Set<String>
+  ) {
+    let proposedNames = operations.compactMap(\.recordName)
+    self.init(
+      proposedRecordNames: proposedNames,
+      existingRecordNames: existingRecordNames
+    )
+  }
+
+  /// Direct initializer for tests and manual construction.
+  ///
+  /// Prefer the comparison-based initializers in production code.
+  public init(creates: Set<String>, updates: Set<String>) {
+    self.creates = creates
+    self.updates = updates
+  }
+}