feat: implement PostgreSQL UUID functions (Chapter 9.14)

Add comprehensive server-side UUID generation and extraction functions following PostgreSQL Chapter 9.14 specification.

Generation Functions:
• gen_random_uuid() / uuidv4() - Random UUID (v4) for primary keys
• uuidv7() - Time-ordered UUID (v7) for better index performance
• uuidv7(interval) - Time-shifted UUID for backdating/scheduling

Extraction Functions:
• uuid_extract_version() - Extract version number (1-7)
• uuid_extract_timestamp() - Extract creation timestamp from v1/v7 UUIDs

API Design:
• Dual interface: PostgreSQL.UUID namespace + Foundation.UUID convenience properties
• Ergonomic syntax: .random, .timeOrdered, .v4, .v7
• Type-safe QueryExpression return types
• Proper NULL handling for optional extraction results

Benefits:
• Reduced network roundtrips via server-side generation
• Better B-tree index performance with time-ordered UUIDs
• Extract timestamps without separate createdAt columns
• Full PostgreSQL 9.14 UUID coverage (6/6 functions)

Tests:
• 20 comprehensive test cases covering generation, extraction, composition, and edge cases
• Real-world usage patterns: batch inserts, filtering, ordering
• All 880 tests passing

Documentation:
• Complete DocC documentation with examples and warnings
• Updated _COVERAGE.md with 100% Chapter 9.14 coverage
• Implementation notes explaining v4 vs v7 trade-offs

Author: coenttb

Sources/StructuredQueriesPostgres/Functions/Aggregate/_COVERAGE.md

@@ -148,7 +148,50 @@ Due to Swift's type system, each Select.aggregate method requires 5 overloads:
 - **Reason**: Administration/introspection, not query building
 - **Strategy**: Out of scope for this package
 
+**9.14: UUID Functions**
+- **Reason**: Now fully implemented (6/6 functions)
+- **Status**: ✅ Complete
+- **Coverage**: See dedicated section below
+
 ### Coverage Summary
 - **Core SQL**: ~95% of commonly-used functions implemented
 - **Skipped**: Niche types, administration, and features superseded by better Swift patterns
 - **Philosophy**: Maximize value per line of code, wait for real-world usage to guide additions
+
+## PostgreSQL Chapter 9.14: UUID Functions
+
+| Function | Purpose | Status | Swift API | Notes |
+|----------|---------|--------|-----------|-------|
+| `gen_random_uuid()` | Generate random UUID (v4) | ✅ | `UUID.random` | Most common for primary keys |
+| `uuidv4()` | Alias for gen_random_uuid() | ✅ | `UUID.v4` | Alternative API |
+| `uuidv7()` | Generate time-ordered UUID (v7) | ✅ | `UUID.timeOrdered` | Better index performance |
+| `uuidv7(interval)` | Generate shifted time-ordered UUID | ✅ | `UUID.timeOrdered(shift:)` | For backdating/future-dating |
+| `uuid_extract_version()` | Extract UUID version number | ✅ | `.extractVersion()` | Returns Int? (1-7) |
+| `uuid_extract_timestamp()` | Extract timestamp from v1/v7 | ✅ | `.extractTimestamp()` | Returns Date? (NULL for v4) |
+
+**Coverage**: 6/6 functions (100%)
+
+**Benefits**:
+- Server-side UUID generation reduces network roundtrips
+- Time-ordered UUIDs (v7) provide better B-tree index performance than random (v4)
+- Extract creation time without separate `createdAt` column
+- Type-safe APIs with proper NULL handling
+
+**Example Usage**:
+```swift
+// Generation
+Event.insert { Event.Draft(id: .timeOrdered, title: "Login") }
+// INSERT INTO "events" ("id", "title") VALUES (uuidv7(), 'Login')
+
+// Extraction
+Event.where { $0.id.extractVersion() == 7 }
+// SELECT … FROM "events" WHERE uuid_extract_version("events"."id") = 7
+
+// Timestamp extraction
+Event.select { $0.id.extractTimestamp() }
+// SELECT uuid_extract_timestamp("events"."id") FROM "events"
+```
+
+**Implementation Files**:
+- `Functions/UUID/UUID+Generation.swift` - Static generation functions
+- `Functions/UUID/UUID+Extraction.swift` - Instance extraction methods

Sources/StructuredQueriesPostgres/Functions/UUID/UUID+Extraction.swift

@@ -0,0 +1,145 @@
+import Foundation
+import StructuredQueriesCore
+
+// MARK: - UUID Extraction Functions
+//
+// PostgreSQL Chapter 9.14: UUID Functions
+// https://www.postgresql.org/docs/18/functions-uuid.html
+//
+// Functions for extracting information from UUIDs
+
+extension QueryExpression where QueryValue == UUID {
+    /// PostgreSQL's `uuid_extract_version()` - Extract UUID version number
+    ///
+    /// Returns the version number (1-7) from a UUID.
+    ///
+    /// ```swift
+    /// User.where { $0.id.extractVersion() == 7 }
+    /// // SELECT … FROM "users" WHERE uuid_extract_version("users"."id") = 7
+    ///
+    /// Event.select {
+    ///     ($0.id, $0.id.extractVersion())
+    /// }
+    /// // SELECT "events"."id", uuid_extract_version("events"."id") FROM "events"
+    /// ```
+    ///
+    /// - Returns: UUID version as Int (1-7), or NULL for non-RFC-9562 variants
+    ///
+    /// **UUID Versions:**
+    /// - `1`: Time-based with MAC address
+    /// - `3`: Name-based with MD5
+    /// - `4`: Random (most common for primary keys)
+    /// - `5`: Name-based with SHA-1
+    /// - `6`: Time-based, reordered (new)
+    /// - `7`: Time-ordered (recommended for databases)
+    ///
+    /// > Note: Returns NULL if the UUID does not conform to RFC 9562 standard.
+    ///
+    /// > Tip: Use this to filter for specific UUID types:
+    /// > `Event.where { $0.id.extractVersion() == 7 }` finds all time-ordered UUIDs.
+    public func extractVersion() -> some QueryExpression<Int?> {
+        SQLQueryExpression(
+            "uuid_extract_version(\(self.queryFragment))",
+            as: Int?.self
+        )
+    }
+
+    /// PostgreSQL's `uuid_extract_timestamp()` - Extract timestamp from UUID
+    ///
+    /// Returns the embedded timestamp from UUIDv1 or UUIDv7.
+    /// Returns NULL for other UUID versions.
+    ///
+    /// ```swift
+    /// Event.select { $0.id.extractTimestamp() }
+    /// // SELECT uuid_extract_timestamp("events"."id") FROM "events"
+    ///
+    /// Event.where {
+    ///     $0.id.extractTimestamp() != nil &&
+    ///     $0.id.extractTimestamp()! > Date.currentDate
+    /// }
+    /// // SELECT … FROM "events"
+    /// // WHERE uuid_extract_timestamp("events"."id") IS NOT NULL
+    /// //   AND uuid_extract_timestamp("events"."id") > CURRENT_DATE
+    /// ```
+    ///
+    /// - Returns: Timestamp with time zone, or NULL if UUID is not v1 or v7
+    ///
+    /// > Note: Only UUIDv1 and UUIDv7 contain extractable timestamps.
+    /// > UUIDv4 (random) will return NULL.
+    ///
+    /// > Tip: Check version first to ensure timestamp exists:
+    /// > ```swift
+    /// > Event.where {
+    /// >     $0.id.extractVersion() == 7 &&
+    /// >     $0.id.extractTimestamp()! > someDate
+    /// > }
+    /// > ```
+    ///
+    /// **NULL Handling Examples:**
+    /// ```swift
+    /// // Filter only UUIDs with timestamps
+    /// Event.where { $0.id.extractTimestamp() != nil }
+    ///
+    /// // Safely compare after NULL check
+    /// Event.where {
+    ///     let timestamp = $0.id.extractTimestamp()
+    ///     timestamp != nil && timestamp! > someDate
+    /// }
+    ///
+    /// // Combine with version check for type safety
+    /// Event.where {
+    ///     $0.id.extractVersion() == 7 &&
+    ///     $0.id.extractTimestamp()! >= Date().addingTimeInterval(-3600)
+    /// }
+    /// ```
+    ///
+    /// **Use cases:**
+    /// - Query events by embedded timestamp without separate `createdAt` column
+    /// - Analyze temporal distribution of UUIDv7-keyed records
+    /// - Audit when records were created server-side
+    /// - Time-based partitioning using UUID timestamps
+    public func extractTimestamp() -> some QueryExpression<Date?> {
+        SQLQueryExpression(
+            "uuid_extract_timestamp(\(self.queryFragment))",
+            as: Date?.self
+        )
+    }
+}
+
+// MARK: - Optional UUID Extraction
+
+extension QueryExpression where QueryValue == UUID? {
+    /// PostgreSQL's `uuid_extract_version()` - Extract UUID version number from optional UUID
+    ///
+    /// Returns the version number (1-7) from an optional UUID, or NULL if the UUID is NULL.
+    ///
+    /// ```swift
+    /// User.select { $0.alternateId.extractVersion() }
+    /// // SELECT uuid_extract_version("users"."alternateId") FROM "users"
+    /// ```
+    ///
+    /// - Returns: UUID version as Int?, or NULL if input is NULL or non-RFC-9562
+    public func extractVersion() -> some QueryExpression<Int?> {
+        SQLQueryExpression(
+            "uuid_extract_version(\(self.queryFragment))",
+            as: Int?.self
+        )
+    }
+
+    /// PostgreSQL's `uuid_extract_timestamp()` - Extract timestamp from optional UUID
+    ///
+    /// Returns the embedded timestamp from an optional UUIDv1 or UUIDv7, or NULL.
+    ///
+    /// ```swift
+    /// Event.select { $0.optionalId.extractTimestamp() }
+    /// // SELECT uuid_extract_timestamp("events"."optionalId") FROM "events"
+    /// ```
+    ///
+    /// - Returns: Timestamp with time zone, or NULL if input is NULL or not v1/v7
+    public func extractTimestamp() -> some QueryExpression<Date?> {
+        SQLQueryExpression(
+            "uuid_extract_timestamp(\(self.queryFragment))",
+            as: Date?.self
+        )
+    }
+}