@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swiftdata/references/swiftdata-advanced.md

@@ -1,976 +1,583 @@
-# SwiftData Advanced Reference
-
-Deep reference for custom data stores, history tracking, CloudKit integration,
-Core Data coexistence, batch operations, complex predicates, composite
-attributes, model inheritance, multiple containers, undo/redo, and preview
-patterns.
-
----
+# SwiftData: advanced topics
 
 ## Contents
 
-- [Custom Data Stores (iOS 18+)](#custom-data-stores-ios-18)
-- [History Tracking and Change Detection (iOS 18+)](#history-tracking-and-change-detection-ios-18)
-- [CloudKit Integration](#cloudkit-integration)
-- [Core Data Coexistence and Migration](#core-data-coexistence-and-migration)
-- [Batch Operations and Performance](#batch-operations-and-performance)
-- [Complex #Predicate Patterns](#complex-predicate-patterns)
-- [Composite Attributes (iOS 18+)](#composite-attributes-ios-18)
-- [Model Inheritance (iOS 26+)](#model-inheritance-ios-26)
-- [Multiple ModelContainer Configurations](#multiple-modelcontainer-configurations)
-- [Undo/Redo Support](#undoredo-support)
-- [Preview Patterns with In-Memory Stores](#preview-patterns-with-in-memory-stores)
-- [Notification Observation](#notification-observation)
-- [Error Handling](#error-handling)
+- [Custom data stores](#custom-data-stores)
+- [History tracking](#history-tracking)
+- [CloudKit in detail](#cloudkit-in-detail)
+- [Core Data strategies](#core-data-strategies)
+- [Batch work and performance](#batch-work-and-performance)
+- [Complex predicates](#complex-predicates)
+- [Codable structs as composite attributes](#codable-structs-as-composite-attributes)
+- [Model inheritance](#model-inheritance)
+- [Several configurations in one container](#several-configurations-in-one-container)
+- [Undo and redo](#undo-and-redo)
+- [Previews with in-memory stores](#previews-with-in-memory-stores)
+- [Save notifications](#save-notifications)
+- [Errors](#errors)
 
-## Custom Data Stores (iOS 18+)
+## Custom data stores
 
-### DataStore Protocol
+From iOS 18 you can replace the SQLite backend by conforming to `DataStore`:
+a JSON file, a cache, a REST service, anything that can answer fetches and
+accept saves.
 
-Implement the `DataStore` protocol to replace the default SQLite-backed store
-with a custom persistence backend (JSON files, in-memory caches, REST APIs,
-etc.).
+Shape of a store:
 
 ```swift
-final class JSONStore: DataStore {
-    typealias Configuration = JSONStoreConfiguration
+import SwiftData
+import Foundation
+
+struct ArchiveStoreConfiguration: DataStoreConfiguration {
+    typealias Store = ArchiveStore
+    var name: String
+    var schema: Schema?
+    let fileURL: URL
+
+    func validate() throws {
+        guard fileURL.isFileURL else { throw DataStoreError.unsupportedFeature }
+    }
+}
+
+final class ArchiveStore: DataStore {
+    typealias Configuration = ArchiveStoreConfiguration
     typealias Snapshot = DefaultSnapshot
 
-    let configuration: JSONStoreConfiguration
+    let configuration: ArchiveStoreConfiguration
     let identifier: String
     let schema: Schema
 
-    init(_ configuration: JSONStoreConfiguration,
+    init(_ configuration: ArchiveStoreConfiguration,
          migrationPlan: (any SchemaMigrationPlan.Type)?) throws {
         self.configuration = configuration
         self.identifier = configuration.name
         self.schema = configuration.schema ?? Schema()
     }
 
-    func fetch<T: PersistentModel>(
-        _ request: DataStoreFetchRequest<T>
-    ) throws -> DataStoreFetchResult<T, DefaultSnapshot> {
-        // Load data from JSON file, apply predicate/sort from request.descriptor
-        let snapshots: [DefaultSnapshot] = []  // Populate from file
-        return DataStoreFetchResult(
-            descriptor: request.descriptor,
-            fetchedSnapshots: snapshots,
-            relatedSnapshots: [:]
-        )
-    }
-
-    func fetchCount<T: PersistentModel>(
-        _ request: DataStoreFetchRequest<T>
-    ) throws -> Int {
-        try fetch(request).fetchedSnapshots.count
+    func fetch<T>(_ request: DataStoreFetchRequest<T>) throws
+        -> DataStoreFetchResult<T, Snapshot> where T: PersistentModel {
+        let snapshots: [DefaultSnapshot] = []   // read from the archive, apply request.descriptor
+        return DataStoreFetchResult(descriptor: request.descriptor,
+                                    fetchedSnapshots: snapshots,
+                                    relatedSnapshots: [:])
     }
 
-    func fetchIdentifiers<T: PersistentModel>(
-        _ request: DataStoreFetchRequest<T>
-    ) throws -> [PersistentIdentifier] {
-        try fetch(request).fetchedSnapshots.map(\.persistentIdentifier)
-    }
-
-    func save(
-        _ request: DataStoreSaveChangesRequest<DefaultSnapshot>
-    ) throws -> DataStoreSaveChangesResult<DefaultSnapshot> {
-        // Persist inserted, updated; remove deleted
-        return DataStoreSaveChangesResult(
-            for: identifier,
-            remappedIdentifiers: [:],
-            snapshotsToReregister: [:]
-        )
-    }
-
-    func erase() throws {
-        // Remove all persisted data
-    }
-
-    func initializeState(for editingState: EditingState) {}
-    func invalidateState(for editingState: EditingState) {}
-
-    func cachedSnapshots(
-        for identifiers: [PersistentIdentifier],
-        editingState: EditingState
-    ) throws -> [PersistentIdentifier: DefaultSnapshot] {
-        [:]
+    func save(_ request: DataStoreSaveChangesRequest<Snapshot>) throws
+        -> DataStoreSaveChangesResult<Snapshot> {
+        // write request.inserted, request.updated, request.deleted
+        DataStoreSaveChangesResult(for: identifier,
+                                   remappedIdentifiers: [:],
+                                   snapshotsToReregister: [:])
     }
 }
 ```
 
-### DataStoreConfiguration
-
-```swift
-struct JSONStoreConfiguration: DataStoreConfiguration {
-    typealias Store = JSONStore
-
-    let name: String
-    var schema: Schema?
-    let fileURL: URL
-
-    init(name: String, fileURL: URL) {
-        self.name = name
-        self.fileURL = fileURL
-    }
-
-    func validate() throws {
-        // Validate file URL is accessible
-    }
-}
-```
+The sketch shows the two central members. The protocol also requires
+`fetchCount`, `fetchIdentifiers`, `erase()`, `initializeState(for: EditingState)`,
+`invalidateState(for:)` and `cachedSnapshots(for:editingState:)`.
 
-### Using a Custom Store
+Use it like any other configuration:
 
 ```swift
-let config = JSONStoreConfiguration(
-    name: "JSONStore",
-    fileURL: URL.documentsDirectory.appending(path: "data.json")
-)
-let container = try ModelContainer(
-    for: Trip.self,
-    configurations: config
-)
+let archive = ArchiveStoreConfiguration(name: "Archive", schema: nil, fileURL: archiveURL)
+let archivedNotes = try ModelContainer(for: ArchivedNote.self, configurations: archive)
 ```
 
-### Optional Conformances
+Optional extras:
 
-- **`DataStoreBatching`**: Implement `delete(_:)` for batch delete support.
-- **`HistoryProviding`**: Implement `fetchHistory(_:)` and `deleteHistory(_:)`
-  for change tracking.
+- `DataStoreBatching` adds `delete(_:)` for batch deletes.
+- `HistoryProviding` adds `fetchHistory(_:)` and `deleteHistory(_:)`.
 
-### DataStoreError Cases
+When a request is beyond the store, throw a `DataStoreError`:
+`.invalidPredicate`, `.preferInMemoryFilter` (SwiftData filters in memory
+instead), `.preferInMemorySort`, or `.unsupportedFeature`.
 
-Handle these when implementing custom stores:
+## History tracking
 
-| Case | Meaning |
-|------|---------|
-| `.invalidPredicate` | Predicate cannot be evaluated by the store |
-| `.preferInMemoryFilter` | Store cannot filter; framework filters in memory |
-| `.preferInMemorySort` | Store cannot sort; framework sorts in memory |
-| `.unsupportedFeature` | Store does not support the requested operation |
+From iOS 18 the default store records a history of transactions, so an app can
+catch up on what changed since it last looked, including changes made by
+widgets and extensions.
 
----
+Label your own writes:
 
-## History Tracking and Change Detection (iOS 18+)
-
-### Enable History Tracking
+```swift
+context.author = "main-app"
+```
 
-Set the `author` property on `ModelContext` to tag changes with an identifier.
-Mark attributes with `.preserveValueOnDeletion` to retain values in tombstones
-after deletion.
+Mark attributes whose values should survive into deletion records:
 
 ```swift
 @Model
-class Trip {
-    @Attribute(.preserveValueOnDeletion) var name: String
-    @Attribute(.preserveValueOnDeletion) var destination: String
-    var startDate: Date
-
-    init(name: String, destination: String, startDate: Date) {
-        self.name = name
-        self.destination = destination
-        self.startDate = startDate
-    }
+final class Receipt {
+    @Attribute(.preserveValueOnDeletion) var number: String
+    var amount: Decimal
+    init(number: String, amount: Decimal) { self.number = number; self.amount = amount }
 }
-
-// Tag context for history attribution
-modelContext.author = "mainApp"
 ```
 
-### Fetch History Transactions
+Read changes since a saved token. `mirror` stands in for whatever your app does
+with each change (refresh a cache, update a widget, push to a server). The
+`.update` and `.delete` payloads are existentials, so cast them to
+`DefaultHistoryUpdate<Model>` / `DefaultHistoryDelete<Model>` before reading
+`updatedAttributes` or `tombstone`; a tombstone value comes back as
+`(any Sendable)?`:
 
 ```swift
-var descriptor = HistoryDescriptor<DefaultHistoryTransaction>()
-
-// Filter by token (only new changes since last check)
-if let lastToken = savedToken {
-    descriptor.predicate = #Predicate<DefaultHistoryTransaction> { transaction in
-        transaction.token > lastToken
+func applyChanges(since lastToken: DefaultHistoryToken?,
+                  in context: ModelContext,
+                  mirror: HistoryMirror) throws -> DefaultHistoryToken? {
+    var descriptor = HistoryDescriptor<DefaultHistoryTransaction>()
+    if let lastToken {
+        descriptor.predicate = #Predicate { $0.token > lastToken }
     }
-}
-
-// iOS 26+: Sort by timestamp
-descriptor.sortBy = [SortDescriptor(\.timestamp, order: .reverse)]
-
-let transactions = try modelContext.fetchHistory(descriptor)
-
-for transaction in transactions {
-    for change in transaction.changes {
-        switch change {
-        case .insert(let insert):
-            let insertedID = insert.changedPersistentIdentifier
-            // Process new record
-
-        case .update(let update):
-            let updatedID = update.changedPersistentIdentifier
-            let changedAttributes = update.updatedAttributes
-            // Process modification
-
-        case .delete(let delete):
-            let deletedID = delete.changedPersistentIdentifier
-            let tombstone = delete.tombstone
-            // Access preserved values
-            if let name = tombstone[\.name] as? String {
-                // Use preserved name for sync/audit
+    let transactions = try context.fetchHistory(descriptor)
+    for transaction in transactions {
+        for change in transaction.changes {
+            switch change {
+            case .insert(let inserted):
+                mirror.added(inserted.changedPersistentIdentifier)
+            case .update(let updated):
+                if let receipt = updated as? DefaultHistoryUpdate<Receipt> {
+                    mirror.changed(receipt.changedPersistentIdentifier,
+                                   fields: receipt.updatedAttributes)
+                }
+            case .delete(let deleted):
+                if let receipt = deleted as? DefaultHistoryDelete<Receipt> {
+                    mirror.removed(receipt.changedPersistentIdentifier,
+                                   number: receipt.tombstone[\.number] as? String)
+                }
+            @unknown default:
+                break
             }
         }
     }
-
-    // Save token for next incremental fetch
-    savedToken = transaction.token
+    return transactions.last?.token ?? lastToken
 }
 ```
 
-### Delete Stale History
+Persist the returned token and pass it in next time. Sorting a
+`HistoryDescriptor` by `\.timestamp` needs iOS 26.
 
-```swift
-let cutoffDate = Calendar.current.date(byAdding: .month, value: -3, to: .now)!
-var descriptor = HistoryDescriptor<DefaultHistoryTransaction>()
-descriptor.predicate = #Predicate<DefaultHistoryTransaction> { transaction in
-    transaction.timestamp < cutoffDate
-}
-try modelContext.deleteHistory(descriptor)
-```
-
-### DefaultHistoryTransaction Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `author` | `String?` | The context author that made the change |
-| `changes` | `[HistoryChange]` | Insert, update, delete changes |
-| `storeIdentifier` | `String` | Store that owns the transaction |
-| `timestamp` | `Date` | When the transaction occurred |
-| `token` | `DefaultHistoryToken` | Opaque token for incremental queries |
-| `transactionIdentifier` | ... | Unique transaction ID |
-| `bundleIdentifier` | `String` | Bundle that made the change |
-| `processIdentifier` | `String` | Process that made the change |
-
-### Cross-Process Change Detection
-
-Use `bundleIdentifier` and `processIdentifier` to differentiate changes from
-widgets, extensions, or the main app.
+Prune old history so it does not grow forever:
 
 ```swift
-for transaction in transactions {
-    if transaction.author == "widget" {
-        // Handle widget-originated changes
-    }
-}
+let cutoff = Date.now.addingTimeInterval(-90 * 24 * 60 * 60)
+var old = HistoryDescriptor<DefaultHistoryTransaction>()
+old.predicate = #Predicate { $0.timestamp < cutoff }
+try context.deleteHistory(old)
 ```
 
----
-
-## CloudKit Integration
+`DefaultHistoryTransaction` carries `author`, `changes`, `storeIdentifier`,
+`timestamp`, `token` (a `DefaultHistoryToken`), `transactionIdentifier`,
+`bundleIdentifier` and `processIdentifier`. Use `author`, `bundleIdentifier`
+and `processIdentifier` to tell app, widget and extension writes apart.
 
-### Configuration Options
+## CloudKit in detail
 
-```swift
-// Automatic: uses CloudKit entitlement from the app
-let autoConfig = ModelConfiguration(
-    cloudKitDatabase: .automatic
-)
+`cloudKitDatabase:` on `ModelConfiguration` takes:
 
-// Explicit private database
-let privateConfig = ModelConfiguration(
-    cloudKitDatabase: .private("iCloud.com.example.myapp")
-)
+- `.automatic`: use the container named in the app's entitlements.
+- `.private("iCloud.example.app")`: a specific private database.
+- `.none`: never sync this store.
 
-// No CloudKit sync
-let localConfig = ModelConfiguration(
-    cloudKitDatabase: .none
-)
-```
-
-### Setup Requirements
+Setup:
 
-1. Enable iCloud capability in Xcode.
-2. Add CloudKit entitlement (`com.apple.developer.icloud-services`).
-3. Configure a CloudKit container identifier.
-4. Enable Background Modes > Remote notifications.
-5. Use the container identifier in `ModelConfiguration`.
+1. Add the iCloud capability to the target.
+2. Check CloudKit; this adds the `com.apple.developer.icloud-services`
+   entitlement.
+3. Pick or create the container identifier.
+4. Under Background Modes, turn on Remote notifications.
+5. Name the same container in `ModelConfiguration`.
 
-### CloudKit-Compatible Model Design
+A model that syncs cleanly:
 
 ```swift
 @Model
-class SyncedNote {
-    // Keep required scalars nonoptional when defaults/initializers support them
-    var title: String = ""
+final class JournalEntry {
+    var headline: String = ""
     var body: String?
+    @Attribute(.allowsCloudEncryption) var mood: String?
+    @Attribute(.externalStorage) var sketch: Data?
+    var notebook: Notebook?
 
-    // Encrypt sensitive fields in CloudKit
-    @Attribute(.allowsCloudEncryption) var secretContent: String?
-
-    // Store large data externally
-    @Attribute(.externalStorage) var attachment: Data?
-
-    // Avoid .unique with CloudKit -- CloudKit does not enforce server-side uniqueness
-    // Use @Attribute(.unique) only for local-only stores
-
-    init(title: String? = nil, body: String? = nil) {
-        self.title = title
+    init(headline: String, body: String? = nil) {
+        self.headline = headline
         self.body = body
     }
 }
 ```
 
-### CloudKit Limitations
+`headline` stays a non-optional `String` with a default, and the initializer
+takes a non-optional value for it.
 
-- **Unique constraints**: CloudKit does not enforce uniqueness server-side.
-  Avoid `@Attribute(.unique)` and `#Unique` on CloudKit-synced models. Use
-  `cloudKitDatabase: .none` for local-only stores that need uniqueness.
-- **Relationships**: CloudKit requires optional relationships. Do not make every
-  scalar optional just for CloudKit; keep required scalars when defaults,
-  initializers, or migrations provide valid values.
-- **Delete rules**: `.deny` is unsupported for CloudKit sync; enforce that
-  invariant in app logic if needed.
-- **Schema changes**: Initialize and verify the development schema in
-  nonproduction builds, promote it before release, and treat production changes
-  as additive-only.
+- CloudKit does not enforce uniqueness on the server, so avoid
+  `@Attribute(.unique)` and `#Unique` in synced models. A store that needs them
+  should use `cloudKitDatabase: .none`.
+- Relationships must be optional. Scalars do not all have to be.
+- `.deny` delete rules are not supported; enforce that invariant in app code.
 
-### Multiple Stores: Local + Synced
+Keeping part of the data local while the rest syncs:
 
 ```swift
-let localConfig = ModelConfiguration(
-    "Local",
-    schema: Schema([DraftNote.self]),
-    cloudKitDatabase: .none
-)
+let syncedSchema = Schema([JournalEntry.self, Notebook.self])
+let localSchema = Schema([DraftCache.self])
 
-let syncedConfig = ModelConfiguration(
-    "Synced",
-    schema: Schema([PublishedNote.self]),
-    cloudKitDatabase: .private("iCloud.com.example.app")
-)
+let synced = ModelConfiguration("Synced", schema: syncedSchema,
+                                cloudKitDatabase: .private("iCloud.example.journal"))
+let local = ModelConfiguration("Local", schema: localSchema,
+                               cloudKitDatabase: .none)
 
 let container = try ModelContainer(
-    for: Schema([DraftNote.self, PublishedNote.self]),
-    configurations: [localConfig, syncedConfig]
+    for: Schema([JournalEntry.self, Notebook.self, DraftCache.self]),
+    configurations: [synced, local]
 )
 ```
 
----
-
-## Core Data Coexistence and Migration
-
-### Three Strategies
-
-| Strategy | When to Use |
-|----------|-------------|
-| Pure Core Data | No migration needed; maintain existing stack |
-| Full SwiftData | Greenfield app or complete rewrite |
-| Coexistence | Gradual migration; both stacks share the same store |
-
-### Coexistence Setup
-
-Both stacks read/write the same SQLite file. Critical requirements:
-
-1. **Enable persistent history tracking** on the Core Data side:
-   ```swift
-   let description = NSPersistentStoreDescription()
-   description.setOption(
-       true as NSNumber,
-       forKey: NSPersistentHistoryTrackingKey
-   )
-   ```
-
-2. **Match entity names** between Core Data `.xcdatamodeld` and SwiftData
-   `@Model` classes.
-
-3. **Use different class names** to avoid conflicts:
-   ```swift
-   // Core Data side
-   class CDTrip: NSManagedObject { /* ... */ }
-
-   // SwiftData side
-   @Model
-   class Trip { /* entity name "Trip" matches Core Data entity */ }
-   ```
+## Core Data strategies
 
-4. **Point both stacks at the same store URL**.
+Three paths for an app that has Core Data today:
 
-### Store File Locations
+| Path | When |
+|---|---|
+| Stay on Core Data | The stack works and nothing needs SwiftData |
+| Move fully to SwiftData | New app, or a planned rewrite |
+| Run both on one store | Gradual move, screen by screen |
 
-| Scenario | Location |
-|----------|----------|
-| Default | Application Support directory |
-| App group entitlement | Root of app group container |
-| Explicit URL | `ModelConfiguration(url: customURL)` |
+Running both requires:
 
-### Migration from Core Data to SwiftData
+- Persistent history on the Core Data side:
+  set `NSPersistentHistoryTrackingKey` to `true` on the store description
+  before loading it.
+- Matching entity names. Keep the Swift class names different so they do not
+  collide, and give the Core Data class the same entity name:
+  `CDInvoice: NSManagedObject` for the entity `Invoice`, and
+  `@Model final class Invoice` on the SwiftData side.
+- Both stacks opening the same store URL.
 
-Step-by-step:
+Where the store lives: by default under Application Support; with an app group,
+at the root of the group container; or anywhere you choose with
+`ModelConfiguration(url:)`.
 
-1. Define `VersionedSchema` matching the current Core Data model.
-2. Create `@Model` classes with matching entity/attribute names.
-3. Set up `SchemaMigrationPlan` for future changes.
-4. Enable persistent history tracking on Core Data side.
-5. Point both stacks at the same store file.
-6. Gradually move reads to `@Query` / `FetchDescriptor`.
-7. Move writes to `ModelContext` operations.
-8. Remove Core Data stack when migration is complete.
+Moving over, in order:
 
----
+1. Write a `VersionedSchema` that matches the current Core Data model.
+2. Write `@Model` classes that match each entity.
+3. Add a `SchemaMigrationPlan`.
+4. Turn on persistent history in Core Data.
+5. Open the shared store file from both stacks.
+6. Move reads to `@Query` and `FetchDescriptor`.
+7. Move writes to `ModelContext`.
+8. Remove the Core Data stack.
 
-## Batch Operations and Performance
-
-### Batch Enumeration
-
-Process large result sets without loading all objects into memory:
-
-```swift
-try modelContext.enumerate(
-    FetchDescriptor<Trip>(),
-    batchSize: 5000,
-    allowEscapingMutations: false
-) { trip in
-    trip.isProcessed = true
-}
-```
-
-- `batchSize`: Number of objects loaded per batch (default 5000).
-- `allowEscapingMutations`: Set to `true` only if mutations need to persist
-  beyond the enumeration block.
-
-### Batch Delete
-
-```swift
-try modelContext.delete(
-    model: Trip.self,
-    where: #Predicate { $0.isArchived == true },
-    includeSubclasses: true  // iOS 26+ with inheritance
-)
-```
-
-### Fetching Only Identifiers
-
-When full objects are not needed (e.g., for counting or cross-actor references):
-
-```swift
-let ids = try modelContext.fetchIdentifiers(FetchDescriptor<Trip>())
-```
-
-### Fetch Count
-
-```swift
-let count = try modelContext.fetchCount(
-    FetchDescriptor<Trip>(predicate: #Predicate { $0.isFavorite == true })
-)
-```
-
-### Partial Property Fetch
-
-Fetch only specific properties to reduce memory:
-
-```swift
-var descriptor = FetchDescriptor<Trip>()
-descriptor.propertiesToFetch = [\.name, \.startDate]
-let trips = try modelContext.fetch(descriptor)
-```
+Details and a migration test: [core-data-coexistence.md](core-data-coexistence.md).
 
-### Relationship Prefetching
+## Batch work and performance
 
-Avoid N+1 query problems by prefetching related objects:
+`delete(model:where:includeSubclasses:)` deletes by predicate without loading
+rows. `includeSubclasses` matters once you use model inheritance (iOS 26+).
 
 ```swift
-var descriptor = FetchDescriptor<Trip>()
-descriptor.relationshipKeyPathsForPrefetching = [\.accommodation, \.tags]
-let trips = try modelContext.fetch(descriptor)
+try context.delete(model: Invoice.self,
+                   where: #Predicate { $0.total == 0 },
+                   includeSubclasses: true)
 ```
 
-### Performance Tips
-
-- Use `fetchLimit` and `fetchOffset` for pagination.
-- Use `enumerate` instead of `fetch` for processing large datasets.
-- Use `fetchCount` when only the count is needed.
-- Use `fetchIdentifiers` when only IDs are needed.
-- Use `propertiesToFetch` to limit loaded data.
-- Use `@Attribute(.externalStorage)` for large `Data` payloads such as images
-  and blobs.
-- Disable `includePendingChanges` if unsaved data is not needed in results.
-- Call `modelContext.save()` periodically during large imports to flush memory.
+Performance habits:
 
----
+- Page with `fetchLimit` and `fetchOffset`.
+- Walk large sets with `enumerate`.
+- Count with `fetchCount`; collect IDs with `fetchIdentifiers`.
+- Load only needed columns with `propertiesToFetch`.
+- Keep blobs out of the table with `.externalStorage`.
+- Set `includePendingChanges = false` when unsaved edits do not matter.
+- In long imports, save every few hundred rows.
 
-## Complex #Predicate Patterns
+## Complex predicates
 
-### Nested Collection Predicates
+These assume an `Invoice` model with `lines`, `client`, `discount`, `memo`,
+`issuedAt`, `total` and `budget`. All outside values are bound before the macro.
 
 ```swift
-// Trips with at least one high-priority tag
-#Predicate<Trip> { trip in
-    trip.tags.contains { tag in
-        tag.priority > 5
-    }
-}
+let minimum = 3
+let cal = Calendar.current
+let week = cal.dateInterval(of: .weekOfYear, for: .now)
+let startOfWeek = week?.start ?? .distantPast
+let endOfWeek = week?.end ?? .distantFuture
+let needle = "tax"
+let searchNotes = true
+let earliest: Date? = nil
 
-// Trips where all items are packed
-#Predicate<Trip> { trip in
-    trip.packingList.allSatisfy { item in
-        item.isPacked == true
-    }
+// Into a to-many relationship
+let hasBigLine = #Predicate<Invoice> { invoice in
+    invoice.lines.contains { $0.quantity > minimum }
 }
-```
-
-### Optional Chaining
-
-```swift
-// Trips with accommodation in a specific city
-#Predicate<Trip> { trip in
-    trip.accommodation?.city == "Paris"
+let allPaid = #Predicate<Invoice> { invoice in
+    invoice.lines.allSatisfy { $0.isPaid }
 }
 
-// Nil coalescing
-#Predicate<Trip> { trip in
-    (trip.accommodation?.rating ?? 0) >= 4
-}
-```
+// Optional chaining and nil coalescing
+let clientInBerlin = #Predicate<Invoice> { $0.client?.city == "Berlin" }
+let lowDiscount = #Predicate<Invoice> { ($0.discount ?? 0) < 10 }
 
-### String Operations
+// Prefix and case-insensitive search
+let draftNumber = #Predicate<Invoice> { $0.number.starts(with: "DRAFT-") }
+let mentionsTax = #Predicate<Invoice> { $0.memo.localizedStandardContains(needle) }
 
-```swift
-// Case-insensitive search
-#Predicate<Trip> { trip in
-    trip.destination.localizedStandardContains(searchText)
-}
+// Date window and arithmetic between properties
+let thisWeek = #Predicate<Invoice> { $0.issuedAt >= startOfWeek && $0.issuedAt < endOfWeek }
+let overBudget = #Predicate<Invoice> { $0.total > $0.budget * 1.1 }
 
-// Prefix matching
-#Predicate<Trip> { trip in
-    trip.name.starts(with: "Summer")
+// Ternary chooses the field to search
+let flexible = #Predicate<Invoice> {
+    searchNotes ? $0.memo.localizedStandardContains(needle)
+                : $0.number.localizedStandardContains(needle)
 }
-```
-
-### Date and Numeric Ranges
-
-```swift
-let startOfYear = Calendar.current.date(from: DateComponents(year: 2026, month: 1, day: 1))!
-let endOfYear = Calendar.current.date(from: DateComponents(year: 2026, month: 12, day: 31))!
-
-#Predicate<Trip> { trip in
-    trip.startDate >= startOfYear && trip.startDate <= endOfYear
-}
-
-// Arithmetic
-#Predicate<Trip> { trip in
-    trip.budget - trip.spent > 100.0
-}
-```
-
-### Ternary Expressions
-
-```swift
-#Predicate<Trip> { trip in
-    (trip.isFavorite ? trip.name : trip.destination).localizedStandardContains(searchText)
-}
-```
 
-### Combining Multiple Predicates
-
-Build predicates incrementally using captured variables:
-
-```swift
-func buildPredicate(
-    searchText: String,
-    onlyFavorites: Bool,
-    minDate: Date?
-) -> Predicate<Trip> {
-    #Predicate<Trip> { trip in
-        (searchText.isEmpty || trip.name.localizedStandardContains(searchText))
-        && (!onlyFavorites || trip.isFavorite == true)
-        && (minDate == nil || trip.startDate >= (minDate ?? .distantPast))
-    }
+// Optional parameter that may or may not filter
+let floor = earliest ?? .distantPast
+let sinceMaybe = #Predicate<Invoice> {
+    earliest == nil || $0.issuedAt >= floor
 }
 ```
 
-### Type Casting in Predicates (iOS 26+, with Inheritance)
+With model inheritance (iOS 26+) a predicate can test the concrete type:
 
 ```swift
-// Filter for business trips only
-#Predicate<Trip> { trip in
-    trip is BusinessTrip
-}
+let onlyRecurring = #Predicate<Invoice> { $0 is RecurringInvoice }
 ```
 
----
-
-## Composite Attributes (iOS 18+)
+## Codable structs as composite attributes
 
-Codable structs stored as composite (nested) attributes in the database.
+A `Codable` struct property is stored as a composite attribute
+(`Schema.CompositeAttribute`): its fields become columns in the owning model's
+table rather than a separate table. Optional composites are allowed. Storing
+Codable structs and enums has been supported since SwiftData's first release;
+what varies by OS is how well predicates reach inside them, so test those on
+your oldest deployment target.
 
 ```swift
-struct Address: Codable {
+struct PostalAddress: Codable, Hashable {
     var street: String
     var city: String
-    var state: String
-    var zip: String
+    var postcode: String
 }
 
 @Model
-class Person {
+final class Customer {
     var name: String
-    var homeAddress: Address   // Stored as composite attribute
-    var workAddress: Address?
+    var billing: PostalAddress
+    var shipping: PostalAddress?
 
-    init(name: String, homeAddress: Address) {
+    init(name: String, billing: PostalAddress) {
         self.name = name
-        self.homeAddress = homeAddress
+        self.billing = billing
     }
 }
-```
 
-Composite attributes appear as `Schema.CompositeAttribute` in the schema.
-Sub-properties are stored inline in the same table. Query individual fields
-via key-path navigation in `#Predicate`:
-
-```swift
-#Predicate<Person> { person in
-    person.homeAddress.city == "San Francisco"
-}
+let local = #Predicate<Customer> { $0.billing.city == "Lyon" }
 ```
 
----
-
-## Model Inheritance (iOS 26+)
+## Model inheritance
 
-### Base and Subclass Pattern
+From iOS 26 a `@Model` class can subclass another. The subclass adds stored
+properties and calls `super.init`.
 
 ```swift
+@available(iOS 26, *)
 @Model
-class Trip {
-    var name: String
-    var destination: String
-    var startDate: Date
-    var endDate: Date
-
-    init(name: String, destination: String, startDate: Date, endDate: Date) {
-        self.name = name
-        self.destination = destination
-        self.startDate = startDate
-        self.endDate = endDate
-    }
-}
-
-@Model
-class PersonalTrip: Trip {
-    var companion: String?
+class Invoice {
+    var number: String
+    var total: Decimal
+    init(number: String, total: Decimal) { self.number = number; self.total = total }
 }
 
+@available(iOS 26, *)
 @Model
-class BusinessTrip: Trip {
-    var company: String
-    var expenseReport: Data?
-
-    init(name: String, destination: String, startDate: Date, endDate: Date,
-         company: String) {
-        self.company = company
-        super.init(name: name, destination: destination,
-                   startDate: startDate, endDate: endDate)
+final class RecurringInvoice: Invoice {
+    var intervalMonths: Int
+    init(number: String, total: Decimal, intervalMonths: Int) {
+        self.intervalMonths = intervalMonths
+        super.init(number: number, total: total)
     }
 }
 ```
 
-### Querying with Inheritance
+- Fetching `Invoice` returns plain invoices and every subclass.
+- Fetching `RecurringInvoice` returns only that subclass.
+- `ModelContainer(for: Invoice.self)` registers the subclasses too.
 
-```swift
-// Fetch all trips (includes PersonalTrip and BusinessTrip)
-let allTrips = try modelContext.fetch(FetchDescriptor<Trip>())
+## Several configurations in one container
 
-// Fetch only business trips
-let businessTrips = try modelContext.fetch(FetchDescriptor<BusinessTrip>())
+Separate stores with different sync settings: see the local plus synced
+example in [CloudKit in detail](#cloudkit-in-detail).
 
-// Delete with subclass inclusion
-try modelContext.delete(
-    model: Trip.self,
-    where: #Predicate { $0.destination == "Cancelled" },
-    includeSubclasses: true
-)
-```
-
-### Container Registration
-
-Register the base class; subclasses are included automatically:
+A read-only seed store shipped in the bundle:
 
 ```swift
-let container = try ModelContainer(for: Trip.self)
-// PersonalTrip and BusinessTrip are included via inheritance
-```
-
----
-
-## Multiple ModelContainer Configurations
-
-### Separate Stores for Different Data
-
-```swift
-// Local-only data (no sync)
-let localConfig = ModelConfiguration(
-    "Local",
-    schema: Schema([AppSettings.self, CacheEntry.self]),
-    isStoredInMemoryOnly: false,
-    cloudKitDatabase: .none
-)
-
-// Synced data
-let syncConfig = ModelConfiguration(
-    "Synced",
-    schema: Schema([UserDocument.self, SharedNote.self]),
-    cloudKitDatabase: .private("iCloud.com.example.app")
-)
-
-let container = try ModelContainer(
-    for: Schema([AppSettings.self, CacheEntry.self, UserDocument.self, SharedNote.self]),
-    configurations: [localConfig, syncConfig]
-)
+if let seedURL = Bundle.main.url(forResource: "Species", withExtension: "store") {
+    let seed = ModelConfiguration("Seed", schema: Schema([Species.self]),
+                                  url: seedURL, allowsSave: false)
+    let user = ModelConfiguration("User", schema: Schema([Sighting.self]))
+    let fieldGuide = try ModelContainer(for: Schema([Species.self, Sighting.self]),
+                                        configurations: [seed, user])
+}
 ```
 
-### Read-Only Bundled Database
+Sharing with widgets and extensions:
 
 ```swift
-let bundledURL = Bundle.main.url(forResource: "seed", withExtension: "store")!
-let readOnlyConfig = ModelConfiguration(
-    "SeedData",
-    schema: Schema([ReferenceItem.self]),
-    url: bundledURL,
-    allowsSave: false
-)
+let shared = ModelConfiguration(groupContainer: .identifier("group.example.journal"))
 ```
 
-### App Group Sharing (Widget / Extension)
-
-```swift
-let sharedConfig = ModelConfiguration(
-    groupContainer: .identifier("group.com.example.myapp")
-)
-let container = try ModelContainer(for: Trip.self, configurations: sharedConfig)
-```
+## Undo and redo
 
----
-
-## Undo/Redo Support
-
-### Setup
-
-```swift
-let context = ModelContext(container)
-context.undoManager = UndoManager()
-```
-
-### SwiftUI Integration
+Give the context an `UndoManager`, for example once at launch:
 
 ```swift
 @main
-struct MyApp: App {
+struct LedgerApp: App {
     let container: ModelContainer
 
     init() {
         do {
-            container = try ModelContainer(for: Trip.self)
-            container.mainContext.undoManager = UndoManager()
+            container = try ModelContainer(for: Invoice.self)
         } catch {
-            fatalError("Failed to create ModelContainer: \(error)")
+            fatalError("Store failed to open: \(error)")
         }
+        container.mainContext.undoManager = UndoManager()
     }
 
     var body: some Scene {
-        WindowGroup {
-            ContentView()
-        }
-        .modelContainer(container)
+        WindowGroup { InvoiceList() }.modelContainer(container)
     }
 }
 ```
 
-### Using Undo/Redo
+Or adopt the window's undo manager from a view:
 
 ```swift
-struct TripEditorView: View {
-    @Environment(\.modelContext) private var modelContext
+struct UndoControls: View {
+    @Environment(\.modelContext) private var context
     @Environment(\.undoManager) private var undoManager
 
     var body: some View {
-        VStack {
-            // ... editing UI ...
-        }
-        .toolbar {
-            ToolbarItemGroup {
-                Button("Undo") {
-                    modelContext.undoManager?.undo()
-                }
-                .disabled(!(modelContext.undoManager?.canUndo ?? false))
-
-                Button("Redo") {
-                    modelContext.undoManager?.redo()
-                }
-                .disabled(!(modelContext.undoManager?.canRedo ?? false))
-            }
-        }
-        .onAppear {
-            modelContext.undoManager = undoManager
+        HStack {
+            Button("Undo") { context.undoManager?.undo() }
+                .disabled(!(context.undoManager?.canUndo ?? false))
+            Button("Redo") { context.undoManager?.redo() }
+                .disabled(!(context.undoManager?.canRedo ?? false))
         }
+        .onAppear { context.undoManager = undoManager }
     }
 }
 ```
 
-Process pending changes to register undo actions:
+After an insert that must be undoable as its own step, call
+`context.processPendingChanges()` so the undo manager records it.
 
-```swift
-modelContext.insert(trip)
-modelContext.processPendingChanges()
-// Now undo is available for the insertion
-```
-
----
-
-## Preview Patterns with In-Memory Stores
+## Previews with in-memory stores
 
-### Basic Preview Container
+One shared container, seeded once:
 
 ```swift
 @MainActor
-let previewContainer: ModelContainer = {
-    let config = ModelConfiguration(isStoredInMemoryOnly: true)
-    let container = try! ModelContainer(for: Trip.self, configurations: config)
-
-    // Seed sample data
-    let sampleTrips = [
-        Trip(name: "Summer in Paris", destination: "Paris",
-             startDate: .now, endDate: .now.addingTimeInterval(86400 * 7)),
-        Trip(name: "Tokyo Adventure", destination: "Tokyo",
-             startDate: .now.addingTimeInterval(86400 * 30),
-             endDate: .now.addingTimeInterval(86400 * 37)),
-    ]
-    for trip in sampleTrips {
-        container.mainContext.insert(trip)
+let sampleLedger: ModelContainer = {
+    do {
+        let container = try ModelContainer(
+            for: Customer.self, Invoice.self,
+            configurations: ModelConfiguration(isStoredInMemoryOnly: true)
+        )
+        let customer = Customer(name: "Ada",
+                                billing: PostalAddress(street: "1 Main", city: "Lyon", postcode: "69001"))
+        container.mainContext.insert(customer)
+        container.mainContext.insert(Invoice(number: "INV-1", total: 120))
+        return container
+    } catch {
+        fatalError("Preview store failed: \(error)")
     }
-
-    return container
 }()
 
-#Preview {
-    TripListView()
-        .modelContainer(previewContainer)
-}
-```
-
-### Preview with Relationships
-
-```swift
-#Preview {
-    let config = ModelConfiguration(isStoredInMemoryOnly: true)
-    let container = try! ModelContainer(
-        for: Trip.self, LivingAccommodation.self,
-        configurations: config
-    )
-
-    let trip = Trip(name: "Beach Trip", destination: "Malibu",
-                    startDate: .now, endDate: .now.addingTimeInterval(86400 * 3))
-    let hotel = LivingAccommodation(name: "Beach Resort")
-    trip.accommodation = hotel
-
-    container.mainContext.insert(trip)
-
-    return TripDetailView(trip: trip)
-        .modelContainer(container)
-}
+#Preview { InvoiceList().modelContainer(sampleLedger) }
 ```
 
-### Preview Trait (iOS 18+)
+With relationships, register every related type, connect the objects, then
+insert the parent; inserting the parent inserts the children with it.
 
-Use `PreviewModifier` for reusable preview configurations:
+From iOS 18, a `PreviewModifier` builds the container once and shares it across
+previews:
 
 ```swift
-struct SampleDataPreview: PreviewModifier {
-    static func makeSharedContext() async throws -> ModelContainer {
-        let config = ModelConfiguration(isStoredInMemoryOnly: true)
-        let container = try ModelContainer(for: Trip.self, configurations: config)
-        // Insert sample data
+struct LedgerSampleData: PreviewModifier {
+    typealias Context = ModelContainer
+
+    static func makeSharedContext() async throws -> Context {
+        let container = try ModelContainer(
+            for: Invoice.self,
+            configurations: ModelConfiguration(isStoredInMemoryOnly: true)
+        )
+        container.mainContext.insert(Invoice(number: "INV-7", total: 42))
         return container
     }
 
-    func body(content: Content, context: ModelContainer) -> some View {
+    func body(content: Content, context: Context) -> some View {
         content.modelContainer(context)
     }
 }
 
-extension PreviewTrait where T == Preview.ViewTraits {
-    static var sampleData: Self = .modifier(SampleDataPreview())
+extension PreviewTrait<Preview.ViewTraits> {
+    @MainActor static var ledgerSample: Self = .modifier(LedgerSampleData())
 }
 
-#Preview(traits: .sampleData) {
-    TripListView()
-}
+#Preview(traits: .ledgerSample) { InvoiceList() }
 ```
 
----
-
-## Notification Observation
+## Save notifications
 
-### Observing Save Events
+Observe `ModelContext.didSave` for a specific context:
 
 ```swift
-NotificationCenter.default.publisher(for: ModelContext.didSave, object: modelContext)
-    .sink { notification in
-        if let insertedIDs = notification.userInfo?[
-            ModelContext.NotificationKey.insertedIdentifiers
-        ] as? Set<PersistentIdentifier> {
-            // Handle new insertions
-        }
-
-        if let updatedIDs = notification.userInfo?[
-            ModelContext.NotificationKey.updatedIdentifiers
-        ] as? Set<PersistentIdentifier> {
-            // Handle updates
-        }
-
-        if let deletedIDs = notification.userInfo?[
-            ModelContext.NotificationKey.deletedIdentifiers
-        ] as? Set<PersistentIdentifier> {
-            // Handle deletions
-        }
-    }
+let token = NotificationCenter.default.addObserver(
+    forName: ModelContext.didSave, object: context, queue: .main
+) { note in
+    let inserted = note.userInfo?[ModelContext.NotificationKey.insertedIdentifiers.rawValue]
+        as? Set<PersistentIdentifier> ?? []
+    refreshBadges(for: inserted)
+}
 ```
 
-### Available Notification Keys
-
-| Key | Description |
-|-----|-------------|
-| `.insertedIdentifiers` | IDs of newly inserted models |
-| `.updatedIdentifiers` | IDs of updated models |
-| `.deletedIdentifiers` | IDs of deleted models |
-| `.invalidatedAllIdentifiers` | All data invalidated (e.g., store reset) |
-| `.queryGeneration` | Query generation token |
-
----
+Keys under `ModelContext.NotificationKey`: `.insertedIdentifiers`,
+`.updatedIdentifiers` and `.deletedIdentifiers` (each a
+`Set<PersistentIdentifier>`), plus `.invalidatedAllIdentifiers` and
+`.queryGeneration`.
 
-## Error Handling
+## Errors
 
-### SwiftDataError Cases
+Catch `SwiftDataError` and compare against its static values:
 
 ```swift
 do {
-    let trips = try modelContext.fetch(descriptor)
+    try context.save()
 } catch let error as SwiftDataError {
     switch error {
-    case SwiftDataError.unsupportedPredicate:
-        // Predicate uses unsupported operations
-    case SwiftDataError.unsupportedSortDescriptor:
-        // Sort descriptor cannot be processed
-    case SwiftDataError.modelValidationFailure:
-        // Model fails validation (e.g., unique constraint)
-    case SwiftDataError.loadIssueModelContainer:
-        // Container could not load the store
+    case .modelValidationFailure:
+        // for example a uniqueness conflict
+        break
+    case .unsupportedPredicate, .unsupportedSortDescriptor:
+        break
+    case .loadIssueModelContainer:
+        break
     default:
-        // Handle other SwiftData errors
+        break
     }
 } catch {
-    // Handle non-SwiftData errors
+    // not a SwiftDataError; without this clause the do-catch is not exhaustive
 }
 ```
 
-### Common Error Categories
+Grouped by where they come from:
 
-| Category | Errors |
-|----------|--------|
+| Area | Errors |
+|---|---|
 | Fetch | `.unsupportedPredicate`, `.unsupportedSortDescriptor`, `.unsupportedKeyPath`, `.includePendingChangesWithBatchSize` |
 | Configuration | `.duplicateConfiguration`, `.configurationFileNameContainsInvalidCharacters`, `.configurationSchemaNotFoundInContainerSchema` |
 | Container | `.loadIssueModelContainer` |