Add distance comparison and app-managed R*Tree tests

- matchesInMemorySwiftFilterAndSort: verifies the SQL distance function
  produces the same filtered set and sort order as filtering/sorting the
  same 200-point dataset in Swift.
- appManagedRTreePrefilter: demonstrates the app-managed R*Tree pattern —
  the app creates an rtree virtual table + sync triggers via execute(),
  uses it as a bounding-box prefilter, then applies the exact distance
  function; result matches a brute-force oracle and the prefilter is sound.

Gate the custom-function tests to Apple platforms and document the limit:
SQLite.swift's createFunction is unreliable on non-Apple platforms and
segfaults on Linux (upstream stephencelis/SQLite.swift#1071).

Author: colemancda

Sources/CoreModelSQLite/Database.swift

@@ -112,6 +112,13 @@ extension SQLiteDatabase: ModelStorage {
         invalidateCache(for: [entity])
     }
 
+    /// Registers a custom scalar function so it can be invoked from a predicate or sort
+    /// descriptor via ``FetchRequest/Predicate/Expression/function(_:)``.
+    ///
+    /// - Important: Only supported on Apple platforms. The underlying SQLite.swift
+    ///   `createFunction` registers the callback through `@convention(block)` +
+    ///   `unsafeBitCast`, which is unreliable on non-Apple platforms and can corrupt
+    ///   SQLite's heap (upstream https://github.com/stephencelis/SQLite.swift/issues/1071).
     public func register(function: DatabaseFunction) async throws {
         connection.register(function: function)
     }

Tests/CoreModelSQLiteTests/CustomFunctionTests.swift

@@ -4,6 +4,14 @@ import CoreModel
 import SQLite
 @testable import CoreModelSQLite
 
+// Custom SQL functions are only exercised on Apple platforms: SQLite.swift's
+// `createFunction` registers the callback with `@convention(block)` + an
+// `unsafeBitCast` to a raw pointer, which is unreliable on non-Apple platforms
+// (the block pointer is invalid and corrupts SQLite's heap — upstream
+// https://github.com/stephencelis/SQLite.swift/issues/1071). Gate these tests to
+// Darwin so CI stays green until that is resolved.
+#if canImport(Darwin)
+
 /// A Haversine distance function, in meters, written directly in the test — CoreModelSQLite
 /// itself has no notion of "distance" or geo data; this exercises the generic
 /// `DatabaseFunction`/`.function` expression mechanism using a realistic example.
@@ -26,8 +34,8 @@ private let distanceFunction = DatabaseFunction(name: "distance", argumentCount:
     return .double(haversineDistance(lat1, lon1, lat2, lon2))
 }
 
-private func makeGeoDatabase() async throws -> SQLiteDatabase {
-    let model = Model(entities: [
+private var geoModel: Model {
+    Model(entities: [
         EntityDescription(
             id: "Site",
             attributes: [
@@ -38,11 +46,35 @@ private func makeGeoDatabase() async throws -> SQLiteDatabase {
             relationships: []
         )
     ])
-    let database = try SQLiteDatabase(path: temporaryDatabasePath(named: "GeoTests"), model: model)
+}
+
+private func makeGeoDatabase(named name: String = "GeoTests") async throws -> SQLiteDatabase {
+    let database = try SQLiteDatabase(path: temporaryDatabasePath(named: name), model: geoModel)
     try await database.register(function: distanceFunction)
     return database
 }
 
+/// A deterministic pseudo-random generator so the large-dataset comparison tests are
+/// reproducible run to run (SPLITMIX64).
+private struct SeededGenerator: RandomNumberGenerator {
+    private var state: UInt64
+    init(seed: UInt64) { state = seed }
+    mutating func next() -> UInt64 {
+        state = state &+ 0x9E3779B97F4A7C15
+        var z = state
+        z = (z ^ (z >> 30)) &* 0xBF58476D1CE4E5B9
+        z = (z ^ (z >> 27)) &* 0x94D049BB133111EB
+        return z ^ (z >> 31)
+    }
+}
+
+private func distanceSort(ascending: Bool = true) -> FetchRequest.SortDescriptor {
+    .init(term: .function(.init(name: "distance", arguments: [
+        .keyPath("latitude"), .keyPath("longitude"),
+        .attribute(.double(referenceLatitude)), .attribute(.double(referenceLongitude))
+    ])), ascending: ascending)
+}
+
 /// Known coordinates, distances computed against Raleigh, NC (35.7796, -78.6382), the
 /// reference point every test below filters/sorts by.
 private let referenceLatitude = 35.7796
@@ -134,17 +166,7 @@ private func expectedIDs(within radiusMeters: Double) -> Set<ObjectID> {
 @MainActor
 @Test func functionRegisteredOnViewContext() async throws {
     let path = temporaryDatabasePath(named: "GeoViewContextTests")
-    let model = Model(entities: [
-        EntityDescription(
-            id: "Site",
-            attributes: [
-                .init(id: "name", type: .string),
-                .init(id: "latitude", type: .double),
-                .init(id: "longitude", type: .double)
-            ],
-            relationships: []
-        )
-    ])
+    let model = geoModel
     let database = try SQLiteDatabase(path: path, model: model)
     try await database.register(function: distanceFunction)
     try await insertSites(database)
@@ -171,3 +193,134 @@ private func expectedIDs(within radiusMeters: Double) -> Set<ObjectID> {
     let count = try await database.count(FetchRequest(entity: "Person"))
     #expect(count == 3)
 }
+
+/// Generate a reproducible spread of coordinates across the continental US and their
+/// precomputed distance from the reference point.
+private func randomSites(count: Int, seed: UInt64) -> [(id: ObjectID, latitude: Double, longitude: Double, distance: Double)] {
+    var rng = SeededGenerator(seed: seed)
+    return (0..<count).map { index in
+        let latitude = Double.random(in: 25...49, using: &rng)
+        let longitude = Double.random(in: -124 ... -67, using: &rng)
+        return (
+            id: ObjectID(rawValue: "site\(index)"),
+            latitude: latitude,
+            longitude: longitude,
+            distance: haversineDistance(latitude, longitude, referenceLatitude, referenceLongitude)
+        )
+    }
+}
+
+/// The SQL `distance` function (executed inside SQLite) must produce exactly the same
+/// filtered set and sort order as filtering/sorting the same data in Swift. Because the
+/// registered function delegates to the same `haversineDistance` Swift code, the two
+/// paths compute bit-identical distances, so the comparison is exact.
+@Test func matchesInMemorySwiftFilterAndSort() async throws {
+    let database = try await makeGeoDatabase(named: "GeoCompare")
+    let generated = randomSites(count: 200, seed: 0xC0FFEE)
+    for site in generated {
+        try await database.insert(ModelData(entity: "Site", id: site.id, attributes: [
+            "latitude": .double(site.latitude),
+            "longitude": .double(site.longitude)
+        ]))
+    }
+
+    let radius = 1_000_000.0 // 1000 km
+
+    // SQL path: filter and sort by the registered distance function
+    let sqlRequest = FetchRequest(
+        entity: "Site",
+        sortDescriptors: [distanceSort()],
+        predicate: .comparison(.init(left: distanceExpression(), right: .attribute(.double(radius)), type: .lessThanOrEqualTo))
+    )
+    let sqlIDs = try await database.fetchID(sqlRequest)
+
+    // In-memory Swift path: same filter and sort over the same data
+    let inMemoryIDs = generated
+        .filter { $0.distance <= radius }
+        .sorted { $0.distance < $1.distance }
+        .map(\.id)
+
+    #expect(sqlIDs == inMemoryIDs)
+    #expect(sqlIDs.isEmpty == false) // ensure the radius actually matched something
+    #expect(sqlIDs.count < generated.count) // ...and excluded something
+}
+
+/// App-managed R*Tree: CoreModelSQLite provides only `execute(_:_:)` and the generic
+/// `distance` function — the app itself creates an R*Tree virtual table (plus a rowid
+/// mapping and triggers to keep it in sync), uses it as a bounding-box prefilter, then
+/// applies the exact `distance` function for correctness. The final result must match
+/// the brute-force in-memory oracle, and the prefilter must be sound (a superset of the
+/// exact matches) and actually prune.
+@Test func appManagedRTreePrefilter() async throws {
+    let path = temporaryDatabasePath(named: "GeoRTree")
+    let database = try SQLiteDatabase(path: path, model: geoModel)
+    try await database.register(function: distanceFunction)
+
+    // App-owned spatial index and sync triggers — entirely outside the library.
+    try await database.execute("""
+        CREATE TABLE "Site_rtree_map" (rowid INTEGER PRIMARY KEY AUTOINCREMENT, site_id TEXT UNIQUE NOT NULL)
+        """)
+    try await database.execute("""
+        CREATE VIRTUAL TABLE "Site_rtree" USING rtree(id, minLat, maxLat, minLon, maxLon)
+        """)
+    try await database.execute("""
+        CREATE TRIGGER "Site_rtree_insert" AFTER INSERT ON "Site" BEGIN
+            INSERT INTO "Site_rtree_map"(site_id) VALUES (NEW."id");
+            INSERT INTO "Site_rtree"(id, minLat, maxLat, minLon, maxLon)
+                SELECT rowid, NEW."latitude", NEW."latitude", NEW."longitude", NEW."longitude"
+                FROM "Site_rtree_map" WHERE site_id = NEW."id";
+        END
+        """)
+
+    let generated = randomSites(count: 200, seed: 0xBEEF)
+    for site in generated {
+        try await database.insert(ModelData(entity: "Site", id: site.id, attributes: [
+            "latitude": .double(site.latitude),
+            "longitude": .double(site.longitude)
+        ]))
+    }
+
+    let radius = 1_000_000.0 // 1000 km
+
+    // Bounding box (a superset of the radius circle) in degrees.
+    let latDelta = radius / 111_320.0
+    let lonDelta = radius / (111_320.0 * cos(referenceLatitude * .pi / 180))
+    let minLat = referenceLatitude - latDelta
+    let maxLat = referenceLatitude + latDelta
+    let minLon = referenceLongitude - lonDelta
+    let maxLon = referenceLongitude + lonDelta
+
+    // Query the app's R*Tree (through the app's own read connection) for candidate ids.
+    let reader = try Connection(path, readonly: true)
+    let candidates = Set(try reader.prepare("""
+        SELECT m.site_id FROM "Site_rtree" r
+        JOIN "Site_rtree_map" m ON m.rowid = r.id
+        WHERE r.minLat <= ? AND r.maxLat >= ? AND r.minLon <= ? AND r.maxLon >= ?
+        """, maxLat, minLat, maxLon, minLon).compactMap { row in
+            (row[0] as? String).map { ObjectID(rawValue: $0) }
+    })
+
+    // Combine the R*Tree candidate set with the exact distance filter via the library.
+    let request = FetchRequest(
+        entity: "Site",
+        sortDescriptors: [distanceSort()],
+        predicate: .compound(.and([
+            .comparison(.init(left: .keyPath("id"), right: .relationship(.toMany(Array(candidates))), type: .in)),
+            .comparison(.init(left: distanceExpression(), right: .attribute(.double(radius)), type: .lessThanOrEqualTo))
+        ]))
+    )
+    let rtreeResult = try await database.fetchID(request)
+
+    // Brute-force oracle over the same data.
+    let oracle = generated
+        .filter { $0.distance <= radius }
+        .sorted { $0.distance < $1.distance }
+        .map(\.id)
+
+    #expect(rtreeResult == oracle)                       // combined query is correct
+    #expect(Set(oracle).isSubset(of: candidates))        // prefilter is sound
+    #expect(candidates.count < generated.count)          // prefilter actually pruned
+    #expect(oracle.isEmpty == false)
+}
+
+#endif // canImport(Darwin)