RouteProvider and the Traits a Child Declares

public protocol RouteProvider: Sendable {
  /// Stable id recorded on every place and route it produces (`apple`).
  var id: String { get }
  /// The name shown to Dad when he picks or is told about a provider.
  var displayName: String { get }
  /// Where it routes, by which modes, and who guides.
  var traits: ProviderTraits { get }

  /// Places matching `query`, nearest to `near` first when given.
  func search(_ query: String, near: Coordinate?, limit: Int) async throws -> [Place]

  /// Driving routes from `origin` to `destination`, best first. `heading` is
  /// the car's current course, when known, so a reroute does not begin with a
  /// U-turn the car cannot make.
  func routes(from origin: Coordinate, heading: Double?, to destination: Place, options: RouteOptions)
    async throws -> [NavRoute]

  /// A fresh travel time from `origin` to `destination` (traffic-aware when
  /// the provider has traffic), for keeping the ETA honest mid-drive. It is
  /// asked with the drive's own `options` (its mode, the roads Dad told it to
  /// stay off): a time asked without them is the time of another road.
  func travelTime(from origin: Coordinate, to destination: Place, options: RouteOptions) async throws
    -> TimeInterval?
}

extension RouteProvider {
  /// Apple's shape: everywhere, by car and on foot, guided by Pathfinder.
  public var traits: ProviderTraits { ProviderTraits() }
}

/// What a stack can do and how it guides. Each child of `RouteProvider`
/// declares its own; consumers ask the root and never name a provider.
public struct ProviderTraits: Equatable, Sendable {
  public enum Guide: Equatable, Sendable {
    /// Pathfinder's engine guides along the provider's route.
    case pathfinder
    /// The provider's own engine guides and draws (Google's Navigation SDK):
    /// its route has no steps for Pathfinder to read, and what Pippa says comes
    /// from the provider's turn feed.
    case provider
  }

  public var guide: Guide
  /// The route's geometry may be drawn on a map that is not the provider's
  /// (the watch draws on Apple's).
  public var routeIsPortable: Bool
  public var regions: Set<MapRegion>
  public var modes: Set<TravelMode>

  public init(
    guide: Guide = .pathfinder, routeIsPortable: Bool = true, regions: Set<MapRegion> = [.korea, .overseas],
    modes: Set<TravelMode> = [.driving, .walking]
  ) {
    self.guide = guide
    self.routeIsPortable = routeIsPortable
    self.regions = regions
    self.modes = modes
  }

  /// The travel modes offered in `region`, car first.
  public func modes(in region: MapRegion) -> [TravelMode] {
    guard regions.contains(region) else { return [] }
    return TravelMode.allCases.filter(modes.contains)
  }
}

// A minimal sketch of "the map is an adapter": one root protocol, children
// that declare what they can do, and consumers that only ever ask the root.
struct Coordinate: Hashable { var lat: Double; var lon: Double }
enum Region: Hashable { case korea, overseas }
enum Mode: String, CaseIterable { case driving, walking }

struct Traits {
  enum Guide { case pathfinder, provider }
  var guide: Guide = .pathfinder
  var routeIsPortable = true
  var regions: Set<Region> = [.korea, .overseas]
  var modes: Set<Mode> = [.driving, .walking]
  func modes(in region: Region) -> [Mode] {
    guard regions.contains(region) else { return [] }
    return Mode.allCases.filter(modes.contains)
  }
}

/// Where Dad wants to go: a name and a coordinate. No provider owns it.
struct Destination { var name: String; var coordinate: Coordinate; var foundBy: String }
/// What a provider rendered: it stays with that provider.
struct Route { var providerID: String; var to: Destination; var line: [Coordinate] }

protocol RouteProvider {
  var id: String { get }
  var traits: Traits { get }
  func route(to destination: Destination) -> Route
}
extension RouteProvider {
  var traits: Traits { Traits() }  // the root's default is Apple's shape
  func route(to destination: Destination) -> Route {
    Route(providerID: id, to: destination, line: [destination.coordinate])
  }
}

struct Apple: RouteProvider { let id = "apple" }
struct Kakao: RouteProvider {
  let id = "kakao"
  var traits: Traits { Traits(routeIsPortable: false, regions: [.korea]) }
}
struct Google: RouteProvider {
  let id = "google"
  var traits: Traits { Traits(guide: .provider, routeIsPortable: false, regions: [.overseas]) }
}

// Consumers: none of them names a provider.
func lineForTheWatch(_ route: Route, from provider: any RouteProvider) -> [Coordinate]? {
  provider.traits.routeIsPortable ? route.line : nil
}
func whoGuides(_ provider: any RouteProvider) -> String {
  provider.traits.guide == .pathfinder ? "Pathfinder's engine" : "its own engine"
}

// A public landmark (Seoul City Hall), saved after Apple found it.
let home = Destination(name: "Home", coordinate: Coordinate(lat: 37.5665, lon: 126.9780), foundBy: "apple")
for provider in [Apple(), Kakao(), Google()] as [any RouteProvider] {
  let route = provider.route(to: home)
  let korea = provider.traits.modes(in: .korea).map(\.rawValue)
  let abroad = provider.traits.modes(in: .overseas).map(\.rawValue)
  print(provider.id, "| Korea:", korea, "| abroad:", abroad, "| guided by", whoGuides(provider),
        "| watch line:", lineForTheWatch(route, from: provider) != nil, "| routes to", route.to.name)
}
// apple | Korea: ["driving", "walking"] | abroad: ["driving", "walking"] | guided by Pathfinder's engine | watch line: true | routes to Home
// kakao | Korea: ["driving", "walking"] | abroad: [] | guided by Pathfinder's engine | watch line: false | routes to Home
// google | Korea: [] | abroad: ["driving", "walking"] | guided by its own engine | watch line: false | routes to Home