Struct-based Projection with an add-only custom registration API (#242)

[trasch]

Summary

Implements #242 in the agreed design: a struct-based Projection with SRID identity, plus an add-only custom registration API. Stacks on #245.

While a major (breaking) change by nature (public enum → struct), the source impact is deliberately minimized: all 125 built-in projections keep their constant names, so dot-shorthand usage (x == .epsg4326, switch on .kind, etc.) keeps compiling unchanged — the whole in-repo codebase needed only 3 tiny rawValue → srid renames.

Phase A — struct-based Projection

• public struct Projection: Hashable, Codable, Sendable, CustomStringConvertible with SRID identity (custom ==/hash); Codable encodes the raw SRID identically to the enum's wire format (decode throws for unregistered SRIDs)
• All built-in projections expose the same static let constants; init?(srid:) (with the historical EPSG:3857 aliases), init?(wkt:) (registry-driven + UTM token short-circuit), init?(utmZone:hemisphere:), description, kind/flags, wraparoundExtent, crsLength(fromMeters:), utmZone, utmHemisphere all preserved in shape

Phase B — add-only registration

• public struct CustomProjection: value-type descriptor with @Sendable forward/inverse closures relative to the EPSG:4326 (WGS84) pivot — explicitly documented as the seam where datum-capable definitions (e.g. NAD27, issue Support CRSs on other datums (NAD27, OSGB, CH1903+, ...) #243) would perform datum transformations. Also carries kind, wraparoundExtent, validExtent (new public struct ProjectionExtent), worldBoundingBox, WKT fragment sets
• Projection.register(CustomProjection) -> Bool — add-only by design: rejected for SRID ≤ 0, duplicates and built-in shadowing; no unregister/deactivate path (per review decision — enabling/disabling of built-ins was rejected earlier as performance-neutral and correctness-degrading)
• The registry keeps a Mutex-guarded add-only snapshot store; nothing is ever removed or replaced

Performance — the big win of the definition-capture design

This branch's parallel test run exposed catastrophic contention from per-access registry reads (~924 s full-suite wall time; a graph perf test at 370×). The fix is architectural: Projection values capture their definition at construction — hot paths (projected(to:), kind, clamped(), isValid, wraparoundExtent) read the stored definition with zero locking, and the registry is only used for cold-path lookups (init?(srid:), Codable), WKT matching and registration.

Release-build benchmarks (per coordinate, before → after):

Path	Before (enum, registry)	After (definition capture)
full projected(to:) 4326↔3857	~178 ns (35× baseline)	~43 ns (~1.7× baseline)
4326→UTM→4326	~300 ns	~164 ns
4326→4978→4326	~531 ns	~443 ns

Testing (+6)

CustomProjectionTests: registration rules (duplicate/<= 0/shadowed SRIDs rejected), end-to-end round trips through a custom definition, registry-driven capabilities (validity/clamp/normalize/kind-dispatch on a custom), WKT matching, Codable semantics (register-before-decode), and an 8-task concurrent registration storm.

Note for test authors (surfaced by the suite, documented in the tests): Swift Testing runs tests in parallel against the process-global registry — reserve SRID blocks and use per-registration WKT fragments.

Also adds a Projections section with a CustomProjection example to the README and full DocC throughout.

Full suite: 2488 tests in 180 suites, zero warnings.

[trasch]

Superseded by #250, which consolidates the full projection-genericity chain into a single reviewable PR. All commits are unchanged in #250.