@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftdata/references/indexing.md

@@ -1,75 +1,82 @@
-# SwiftData Indexing
+# Indexing SwiftData models
 
-Indexes speed up queries on frequently filtered or sorted properties.
+## Contents
 
-Docs: [Index macro](https://sosumi.ai/documentation/swiftdata/index(_:)-74ia2)
+- [Declaring indexes with #Index](#declaring-indexes-with-index)
+- [Deciding what to index](#deciding-what-to-index)
+- [Indexes are schema changes](#indexes-are-schema-changes)
+- [Checking that an index is used](#checking-that-an-index-is-used)
 
-## #Index (iOS 18+)
+## Declaring indexes with #Index
 
-### Single-Property Index
+`#Index` is available from iOS 18. Put it inside the `@Model` class body. Each
+array you pass describes one index, so several arrays produce several indexes.
 
 ```swift
+import SwiftData
+import Foundation
+
 @Model
-class Trip {
-    @Attribute(.unique) var id: UUID
-    var destination: String
-    var startDate: Date
-    var isFavorite: Bool
-
-    init(destination: String, startDate: Date) {
-        self.id = UUID()
-        self.destination = destination
-        self.startDate = startDate
-        self.isFavorite = false
+final class Recording {
+    #Index<Recording>([\.venue], [\.recordedAt], [\.isStarred, \.recordedAt])
+
+    @Attribute(.unique) var recordingID: UUID
+    var venue: String
+    var recordedAt: Date
+    var isStarred: Bool
+
+    init(venue: String, recordedAt: Date, isStarred: Bool = false) {
+        self.recordingID = UUID()
+        self.venue = venue
+        self.recordedAt = recordedAt
+        self.isStarred = isStarred
     }
 }
 ```
 
-Use `#Index` on the model to declare indexes:
+In that declaration:
 
-```swift
-@Model
-class Trip {
-    #Index<Trip>([\.destination], [\.startDate])
-    // ...
-}
-```
+- `[\.venue]` and `[\.recordedAt]` are two separate single-column indexes.
+- `[\.isStarred, \.recordedAt]` is one compound index. It helps a query that
+  filters on the first key and orders by the second, such as "starred
+  recordings, newest first". Order the key paths the way the query uses them:
+  filter column first, sort column second.
 
-This creates two single-column indexes: one on `destination` and one on `startDate`.
+## Deciding what to index
 
-### Compound Index
+An index speeds reads and costs something on every write and in store size.
+Add one when the numbers say so.
 
-```swift
-@Model
-class Trip {
-    #Index<Trip>([\.isFavorite, \.startDate])
-    // ...
-}
-```
+Worth indexing:
+
+- A property that appears in `#Predicate` filters over a large collection
+  (roughly a thousand rows or more).
+- A property used as a `SortDescriptor` key over a large collection.
 
-A compound index on `(isFavorite, startDate)` accelerates queries that filter on `isFavorite` and sort by `startDate`.
+Usually not worth it:
 
-## When to Index
+- Collections that stay small (a few hundred rows or fewer).
+- Properties that are rarely part of a query.
+- Properties that change very often; each change updates the index.
+- Very low cardinality columns, such as a `Bool` on a small table.
+- Queries already served by an existing uniqueness constraint or index, unless
+  profiling shows otherwise.
 
-**Index when:**
-- A property appears in `#Predicate` filters on large collections (1000+ rows)
-- A property is used in `SortDescriptor` on large collections
+Index the few hot paths, not every property.
 
-**Don't index when:**
-- The collection is small (< few hundred rows)
-- The property is rarely queried
-- The property changes very frequently (index maintenance cost)
-- The property has very low cardinality (e.g., a Boolean on a small table)
-- Another schema constraint or existing index already covers the query pattern,
-  unless profiling shows a separate index helps
+## Indexes are schema changes
 
-## Index and Migration
+Adding or dropping an index changes the store schema. Test the change on a
+store that looks like real user data before shipping. If the same release also
+changes the model in ways lightweight migration cannot handle, keep a
+`VersionedSchema` and `SchemaMigrationPlan` ready. Never assume an index change
+needs no migration testing.
 
-Treat adding or removing an index as a schema change. Test it on representative
-stores and keep a `VersionedSchema` / `SchemaMigrationPlan` ready for any
-release where the aggregate schema changes exceed SwiftData's automatic
-migration support.
+## Checking that an index is used
 
-## Verifying Index Usage
+Profile with the Core Data template in Instruments; SwiftData's default store
+is SQLite, and the template shows its fetches. A "Full Table Scan" warning on a
+fetch that runs often means that fetch has no usable index. Re-run after adding
+the index to confirm the warning is gone and the fetch time dropped.
 
-Use Instruments > Core Data template to verify that queries use indexes. Look for "Full Table Scan" warnings on frequently executed fetches  -  these indicate a missing index.
+Apple documentation: https://developer.apple.com/documentation/swiftdata/index(_:)

package/pipeline/skills/shared/external/swiftdata/references/predicate-pitfalls.md

@@ -1,54 +1,78 @@
-# #Predicate Pitfalls
+# #Predicate pitfalls
 
-Common runtime crashes and build errors when using `#Predicate` with SwiftData.
+## Contents
 
-## Unsupported Expressions
+- [Why valid Swift can still fail](#why-valid-swift-can-still-fail)
+- [Expressions that fail at runtime](#expressions-that-fail-at-runtime)
+- [What the store understands](#what-the-store-understands)
+- [Capturing values safely](#capturing-values-safely)
+- [Finding the clause that crashes](#finding-the-clause-that-crashes)
 
-`#Predicate` compiles Swift expressions into a query representation. Only a subset of Swift is supported. Unsupported expressions compile but crash at runtime.
+## Why valid Swift can still fail
 
-| Pattern | Crash? | Fix |
-| --- | --- | --- |
-| `$0.name.uppercased() == "PARIS"` | Runtime crash | Use `localizedStandardContains` or `caseInsensitiveCompare` |
-| `$0.name.count > 5` | Runtime crash | Store length in a separate property or filter after fetch |
-| `$0.tags.count == 0` | Runtime crash | Use `$0.tags.isEmpty` (iOS 17.4+) or a stored flag |
-| `$0.name.isEmpty` on optional String | Runtime crash on some OS versions | Use `$0.name == nil \|\| $0.name == ""` |
-| Custom computed property | Runtime crash | Only stored `@Attribute` properties work in predicates |
-| `Date.now` captured by value | Stale predicate | Create a `let now = Date()` before the predicate and capture it |
-| Enum raw value comparison | Runtime crash (pre-iOS 18) | Store the raw value as a separate property, or target iOS 18+ |
-| Loops, declarations, mutation, or switch-heavy control flow | Build error or runtime failure | Use boolean logic, ternary expressions, optional chaining, or optional binding patterns supported by Foundation `Predicate` |
-| Arbitrary method calls | Runtime crash | Only supported methods (see below) work |
+`#Predicate` does not run your closure. It converts the closure into an
+expression tree that the store translates into a query. Only part of Swift has
+a translation, and the compiler does not always know which part. Code outside
+that part can build cleanly and then throw or crash the first time the fetch
+runs.
 
-## Supported Operations
+## Expressions that fail at runtime
 
-**Comparisons:** `==`, `!=`, `<`, `<=`, `>`, `>=`
+| Expression | What goes wrong | Use instead |
+|---|---|---|
+| `$0.title.uppercased() == key` | String transforms are not translated | `localizedStandardContains` or `caseInsensitiveCompare` |
+| `$0.title.count > 5` | `count` on a string is not translated | Store the length as its own property, or filter after fetching |
+| `$0.labels.count == 0` | `count` on a to-many relationship fails | `$0.labels.isEmpty` (iOS 17.4+) or a stored flag |
+| `$0.nickname.isEmpty` where `nickname` is `String?` | Can crash on some OS versions | `$0.nickname == nil` or `$0.nickname == ""` |
+| A computed property on the model | Only stored attributes exist in the store | Query the stored properties it is built from |
+| `$0.dueAt < Date.now` | The date is not the one you meant, and the predicate goes stale | Bind `let now = Date()` first and capture `now` |
+| `$0.state == .open` or `.rawValue` on an enum before iOS 18 | Enum comparison is not translated on older systems | Store the raw value in its own property, or require iOS 18+ |
+| Loops, `let` inside the closure, mutation, heavy `switch` | Build error or runtime failure | Boolean logic, ternaries, optional chaining and binding |
+| Any other method call | Crashes unless it is on the supported list | Restructure around supported operations |
 
-**Logic:** `&&`, `||`, `!`
+`isEmpty` is fine on collections and to-many relationships (from iOS 17.4). The
+warning above is only about `isEmpty` on an optional `String`.
 
-**String:** `localizedStandardContains(_:)`, `contains(_:)`, `starts(with:)`, `caseInsensitiveCompare(_:)`
+## What the store understands
 
-**Collections:** `contains(where:)`, `allSatisfy(_:)`, `filter(_:)`, `.isEmpty`
+- Comparison: `==`, `!=`, `<`, `<=`, `>`, `>=`
+- Logic: `&&`, `||`, `!`
+- Strings: `localizedStandardContains(_:)`, `contains(_:)`, `starts(with:)`,
+  `caseInsensitiveCompare(_:)`
+- Collections: `contains(where:)`, `allSatisfy(_:)`, `filter(_:)`, `isEmpty`
+- Other: optional chaining, `??`, the ternary operator, `+ - * /`, `as?` and `is`
 
-**Other:** optional chaining, nil coalescing (`??`), ternary (`? :`), arithmetic (`+`, `-`, `*`, `/`), type casting (`as?`, `is`)
+## Capturing values safely
 
-## Safe Pattern: Build Predicates Dynamically
+Compute every outside value into a `let` before the macro. The predicate copies
+captured values when it is created, so what you bind is what the query uses.
 
 ```swift
-func tripPredicate(searchText: String, favoritesOnly: Bool) -> Predicate<Trip> {
+import SwiftData
+import Foundation
+
+func openTicketsFilter(matching text: String, urgentOnly: Bool) -> Predicate<Ticket> {
     let now = Date()
-    return #Predicate<Trip> { trip in
-        (searchText.isEmpty || trip.destination.localizedStandardContains(searchText))
-        && (!favoritesOnly || trip.isFavorite)
-        && trip.startDate > now
+    return #Predicate<Ticket> { ticket in
+        ticket.dueAt >= now
+            && (text.isEmpty || ticket.subject.localizedStandardContains(text))
+            && (!urgentOnly || ticket.isUrgent)
     }
 }
 ```
 
-Capture all external values as `let` bindings outside the predicate closure. The predicate captures them by value at creation time.
+Here `text` is a non-optional `String`, so `text.isEmpty` is safe. The
+`text.isEmpty ||` and `!urgentOnly ||` shapes let one predicate serve the
+filtered and unfiltered cases.
 
-## Debugging Predicate Crashes
+## Finding the clause that crashes
 
-When a predicate crashes at runtime with `SwiftData.PredicateError` or `NSInvalidArgumentException`:
+A failing predicate usually surfaces as `SwiftData.PredicateError` or as an
+`NSInvalidArgumentException` from the SQLite layer.
 
-1. Simplify the predicate to a single clause and add clauses back one at a time
-2. Check each clause uses only supported operations on stored properties
-3. Test on the minimum deployment target  -  some operations were added in later iOS versions
+1. Cut the predicate down to a single clause and run the fetch.
+2. Add the other clauses back one at a time until it fails.
+3. For the failing clause, check that it uses only supported operations and
+   only stored properties.
+4. Run the fetch on the oldest OS you deploy to. Several operations were added
+   in later releases and fail only on older systems.