Fix KeyPath-to-column-name resolution on Linux

String(describing: keyPath) produces <computed_0x...> on Linux instead
of the property name, breaking all WHERE, ORDER BY, and SELECT clauses.

Add _keyPathToColumn mapping to Schema protocol that provides explicit
KeyPath→property name resolution. The @Schema macro auto-generates it;
manual schemas provide their own dictionary. All extractFieldName
functions check the mapping first, falling back to string parsing for
backward compatibility on macOS.

Author: Maartz

Sources/Spectro/Core/Protocols/Schema.swift

@@ -1,4 +1,15 @@
 public protocol Schema: Sendable {
     static var tableName: String { get }
     init()
+    /// KeyPath → Swift property name mapping for cross-platform query building.
+    /// On Linux, `String(describing: keyPath)` produces garbage — this provides
+    /// the reliable source of truth. Generated automatically by `@Schema` macro;
+    /// manual schemas should provide their own.
+    static var _keyPathToColumn: [AnyKeyPath: String] { get }
+}
+
+extension Schema {
+    // AnyKeyPath is not Sendable, but the dictionary is immutable
+    // and only read after initialization.
+    nonisolated public static var _keyPathToColumn: [AnyKeyPath: String] { [:] }
 }

Sources/Spectro/Query/JoinQuery.swift

@@ -125,11 +125,6 @@ public struct JoinQueryBuilder<T: Schema, U: Schema>: Sendable {
     }
 }
 
-private func extractFieldName<T: Schema, V>(from keyPath: KeyPath<T, V>, schema: T.Type) -> String {
-    let keyPathString = "\(keyPath)"
-    return keyPathString.components(separatedBy: ".").last ?? keyPathString
-}
-
 // MARK: - Query Extensions for JOIN execution
 
 extension Query {

Sources/Spectro/Query/Query.swift

@@ -533,6 +533,7 @@ public struct Query<T: Schema>: Sendable {
     }
 
     private func extractRelationshipName<Related>(from keyPath: KeyPath<T, SpectroLazyRelation<Related>>) -> String {
+        if let name = T._keyPathToColumn[keyPath] { return name }
         if let propertyName = keyPath.propertyName { return propertyName }
         let keyPathString = String(describing: keyPath)
         if let match = keyPathString.range(of: #"\.\$?([a-zA-Z_][a-zA-Z0-9_]*)>*$"#, options: .regularExpression) {
@@ -675,6 +676,7 @@ public struct QueryBuilder<T: Schema>: Sendable {
     }
 
     private func extractFieldName<V>(from keyPath: KeyPath<T, V>) -> String {
+        if let name = T._keyPathToColumn[keyPath] { return name }
         let keyPathString = "\(keyPath)"
         return keyPathString.components(separatedBy: ".").last ?? keyPathString
     }
@@ -990,7 +992,8 @@ extension JoinField where V: Comparable {
 
 // MARK: - KeyPath Field Name Extraction
 
-private func extractFieldName<T: Schema, V>(from keyPath: KeyPath<T, V>, schema: T.Type) -> String {
+internal func extractFieldName<T: Schema, V>(from keyPath: KeyPath<T, V>, schema: T.Type) -> String {
+    if let name = T._keyPathToColumn[keyPath] { return name }
     let keyPathString = "\(keyPath)"
     return keyPathString.components(separatedBy: ".").last ?? keyPathString
 }

Sources/Spectro/SchemaBuilder/SchemaMacro.swift

@@ -70,6 +70,6 @@
 ///
 /// If you provide your own `tableName` or `init()` in the struct body, the macro
 /// skips generating those members.
-@attached(member, names: named(tableName), named(init))
+@attached(member, names: named(tableName), named(init), named(_keyPathToColumn))
 @attached(extension, conformances: Schema, SchemaBuilder, names: named(build))
 public macro Schema(_ tableName: String) = #externalMacro(module: "SpectroMacros", type: "SchemaMacro")

Sources/SpectroMacros/SchemaMacro.swift

@@ -314,6 +314,25 @@ extension SchemaMacro: MemberMacro {
             decls.append(convInit)
         }
 
+        // --- static let _keyPathToColumn ---
+        let typeName = structDecl.name.text
+        var entries: [String] = []
+        for prop in properties {
+            switch prop.wrapper {
+            case .id, .column, .timestamp, .foreignKey:
+                entries.append("\\\(typeName).\(prop.name): \"\(prop.name)\"")
+            case .hasMany, .hasOne, .belongsTo, .manyToMany:
+                entries.append("\\\(typeName).$\(prop.name): \"\(prop.name)\"")
+            }
+        }
+        let entriesStr = entries.joined(separator: ",\n            ")
+        let keyPathDecl: DeclSyntax = """
+        nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+                \(raw: entriesStr)
+            ]
+        """
+        decls.append(keyPathDecl)
+
         return decls
     }
 }

Tests/SpectroTests/Helpers/TestSchemas.swift

@@ -6,6 +6,15 @@ import Foundation
 struct TestUser: Schema, SchemaBuilder {
     static let tableName = "test_users"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \TestUser.id: "id",
+        \TestUser.name: "name",
+        \TestUser.email: "email",
+        \TestUser.age: "age",
+        \TestUser.isActive: "isActive",
+        \TestUser.createdAt: "createdAt",
+    ]
+
     @ID var id: UUID
     @Column var name: String
     @Column var email: String
@@ -46,6 +55,13 @@ struct TestUser: Schema, SchemaBuilder {
 struct TestUserWithBio: Schema, SchemaBuilder {
     static let tableName = "test_users_bio"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \TestUserWithBio.id: "id",
+        \TestUserWithBio.name: "name",
+        \TestUserWithBio.email: "email",
+        \TestUserWithBio.bio: "bio",
+    ]
+
     @ID var id: UUID
     @Column var name: String
     @Column var email: String
@@ -92,6 +108,12 @@ struct TestMacroUser {
 struct TestColumnOverride: Schema, SchemaBuilder {
     static let tableName = "test_column_overrides"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \TestColumnOverride.id: "id",
+        \TestColumnOverride.name: "name",
+        \TestColumnOverride.email: "email",
+    ]
+
     @ID var id: UUID
     @Column("display_name") var name: String = ""
     @Column var email: String = ""
@@ -113,6 +135,12 @@ struct TestColumnOverride: Schema, SchemaBuilder {
 struct TestWithUuidColumn: Schema, SchemaBuilder {
     static let tableName = "test_with_uuid_columns"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \TestWithUuidColumn.id: "id",
+        \TestWithUuidColumn.externalId: "externalId",
+        \TestWithUuidColumn.name: "name",
+    ]
+
     @ID var id: UUID
     @Column var externalId: UUID
     @Column var name: String
@@ -138,6 +166,11 @@ struct TestWithUuidColumn: Schema, SchemaBuilder {
 struct IntPKItem: Schema, SchemaBuilder {
     static let tableName = "int_pk_items"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \IntPKItem.id: "id",
+        \IntPKItem.name: "name",
+    ]
+
     @ID var id: Int
     @Column var name: String
 
@@ -168,6 +201,11 @@ struct IntPKItem: Schema, SchemaBuilder {
 struct StringPKItem: Schema, SchemaBuilder {
     static let tableName = "string_pk_items"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \StringPKItem.id: "id",
+        \StringPKItem.name: "name",
+    ]
+
     @ID var id: String
     @Column var name: String
 
@@ -193,6 +231,12 @@ struct StringPKItem: Schema, SchemaBuilder {
 struct IntFKChild: Schema, SchemaBuilder {
     static let tableName = "int_fk_children"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \IntFKChild.id: "id",
+        \IntFKChild.label: "label",
+        \IntFKChild.parentId: "parentId",
+    ]
+
     @ID var id: UUID
     @Column var label: String
     @ForeignKey var parentId: Int
@@ -265,6 +309,14 @@ struct RelUserTag {
 struct TestPost: Schema, SchemaBuilder {
     static let tableName = "test_posts"
 
+    nonisolated(unsafe) static let _keyPathToColumn: [AnyKeyPath: String] = [
+        \TestPost.id: "id",
+        \TestPost.title: "title",
+        \TestPost.body: "body",
+        \TestPost.userId: "userId",
+        \TestPost.createdAt: "createdAt",
+    ]
+
     @ID var id: UUID
     @Column var title: String
     @Column var body: String