@tryterra/react-native 0.0.0-stage → 2.1.0

package/ios/TerraBridgeCore/Locked.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// State behind a lock. `Mutex` needs iOS 18, and the floor is 15.
+final class Locked<State>: @unchecked Sendable {
+    private let lock = NSLock()
+    private var state: State
+
+    init(_ state: State) { self.state = state }
+
+    func withLock<Result>(_ body: (inout State) throws -> Result) rethrows -> Result {
+        lock.lock()
+        defer { lock.unlock() }
+        return try body(&state)
+    }
+}

package/ios/TerraBridgeCore/README.md

@@ -0,0 +1 @@
+Copied from hybrid-common by scripts/vendor-bridge-core.js. Do not edit; change hybrid-common.

package/ios/TerraBridgeCore/Rejections.swift

@@ -0,0 +1,130 @@
+import Foundation
+import TerraSDK
+
+/// A thrown error as a value another language can switch on.
+///
+/// The code and retryability come from the SDK (`TerraError.code`, the vocabulary in
+/// `docs/sdk-reference.md`), so there is no table here to drift. What this owns is which parts of
+/// an error are safe to send: nothing in `message` or `details` may carry a health value or text
+/// written by code this SDK does not own.
+enum Rejections {
+
+    static func payload(for error: any Error) -> TerraErrorPayload {
+        switch error {
+        case let error as TerraError:
+            // The broker's own failures reach the SDK through the token provider, which wraps
+            // them. Unwrapped here so `bridge.token_timeout` stays distinct from a provider that
+            // answered with an error.
+            if case .tokenProviderFailed(let underlying) = error, let bridge = underlying as? BridgeError {
+                return payload(for: bridge)
+            }
+            return TerraErrorPayload(
+                code: error.code,
+                retryable: error.isRetryable,
+                message: message(error),
+                source: source(error),
+                details: details(error))
+        case let error as BridgeError:
+            return TerraErrorPayload(
+                code: error.code,
+                retryable: error.isRetryable,
+                message: message(error),
+                details: details(error))
+        case is CancellationError:
+            return platform("the call was cancelled")
+        default:
+            return platform("a platform call failed")
+        }
+    }
+
+    private static func platform(_ message: String) -> TerraErrorPayload {
+        TerraErrorPayload(code: "platform", retryable: false, message: message)
+    }
+
+    /// Two cases wrap an error this SDK did not raise, and its text is as likely to carry a token
+    /// or a reading as to describe the failure, so neither crosses.
+    private static func message(_ error: TerraError) -> String {
+        switch error {
+        case .tokenProviderFailed: return "the host's token provider failed"
+        case .platform: return "a platform call failed"
+        // The SDK's description embeds its cause's, which can be either of the two above.
+        case .rollbackIncomplete(let remaining, let cause):
+            return "the log failed (\(message(cause))) and \(remaining.count) sample(s) could not be removed"
+        default: return error.errorDescription ?? error.code
+        }
+    }
+
+    private static func message(_ error: BridgeError) -> String {
+        switch error {
+        case .notBootstrapped: return "the native bootstrap did not run"
+        case .unsupportedOnPlatform(let op): return "\(op) is not available on iOS"
+        case .tokenTimeout(let timeoutMs): return "the token provider did not answer within \(timeoutMs) ms"
+        case .invalidPayload(let path): return "the payload is invalid at \(path)"
+        }
+    }
+
+    private static func source(_ error: TerraError) -> Source? {
+        switch error {
+        case .notConnected(let source), .linkRevoked(let source), .devIDMismatch(let source),
+            .linkAlreadyRunning(let source):
+            return Conversions.source(source)
+        default:
+            return nil
+        }
+    }
+
+    private static func details(_ error: TerraError) -> BridgeJSON? {
+        switch error {
+        case .routeAwaitingConverter(let type): return bag(["dataType": type.rawValue])
+        case .syncAlreadyRunning(let type): return bag(["dataType": type.rawValue])
+        case .permissionDenied(let category): return bag(["category": category.rawValue])
+        case .sampleNotFound(let id): return bag(["id": id.uuidString])
+        // The cause travels as its code: a nested error's description carries its own detail.
+        case .rollbackIncomplete(let remaining, let cause):
+            return BridgeJSON(["remaining": .number(Double(remaining.count)), "cause": .string(cause.code)])
+        case .distanceNotAttributable(let activity):
+            return bag(["activity": Conversions.sortKey(Conversions.activity(activity))])
+        case .network(let failure): return details(failure)
+        case .tokenProviderFailed, .platform:
+            return nil
+        case .healthDataUnavailable, .notConnected, .tokenUnavailable, .tokenRejected,
+            .userLimitReached, .upgradeRequired, .deviceKeyUnavailable, .signatureRejected,
+            .clockSkewed, .linkRevoked, .devIDMismatch, .linkConflict, .linkAlreadyRunning,
+            .storeLocked, .storeUnreadable, .deadlineExceeded, .authorizationNotDetermined,
+            .bloodPressureIncomplete, .plannedWorkoutUnnamed, .authorizationUnavailableInExtension:
+            return nil
+        @unknown default:
+            return nil
+        }
+    }
+
+    private static func details(_ failure: TerraError.Network) -> BridgeJSON? {
+        switch failure {
+        case .serverError(let status): return number("status", status)
+        case .throttled(let retryAfter):
+            return retryAfter.map { number("retryAfterSeconds", Int($0.rounded(.up))) }
+        // A URLError code says nothing a caller can act on beyond the code itself.
+        case .transport, .offline, .timedOut, .malformedResponse:
+            return nil
+        @unknown default:
+            return nil
+        }
+    }
+
+    private static func details(_ error: BridgeError) -> BridgeJSON? {
+        switch error {
+        case .notBootstrapped(let line): return bag(["line": line])
+        case .unsupportedOnPlatform(let op): return bag(["op": op])
+        case .tokenTimeout(let timeoutMs): return number("timeoutMs", timeoutMs)
+        case .invalidPayload(let path): return bag(["path": path])
+        }
+    }
+
+    private static func bag(_ values: [String: String]) -> BridgeJSON {
+        BridgeJSON(values.mapValues { .string($0) })
+    }
+
+    private static func number(_ key: String, _ value: Int) -> BridgeJSON {
+        BridgeJSON([key: .number(Double(value))])
+    }
+}

package/ios/TerraBridgeCore/RuntimeAttachment.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+public final class RuntimeAttachment: Sendable {
+    private struct State {
+        var attached: BridgeSession?
+        var invalidated = false
+    }
+
+    private let state = Locked(State())
+    private let attach: @Sendable () throws(BridgeRejection) -> BridgeSession
+
+    /// Attaches to what `BridgeBootstrap` parked. `missingLine` is what `bridge.not_bootstrapped` names.
+    public convenience init(
+        missingLine: String,
+        emit: @escaping @Sendable (_ subscriptionId: String, _ message: String) -> Void
+    ) {
+        self.init { () throws(BridgeRejection) -> BridgeSession in
+            try BridgeBootstrap.attach(missingLine: missingLine, emit: emit)
+        }
+    }
+
+    init(attach: @escaping @Sendable () throws(BridgeRejection) -> BridgeSession) {
+        self.attach = attach
+    }
+
+    public func session() throws(BridgeRejection) -> BridgeSession? {
+        let attach = attach
+        let outcome: Result<BridgeSession?, BridgeRejection> = state.withLock { state in
+            if state.invalidated { return .success(nil) }
+            if let attached = state.attached { return .success(attached) }
+            do throws(BridgeRejection) {
+                let session = try attach()
+                state.attached = session
+                return .success(session)
+            } catch {
+                return .failure(error)
+            }
+        }
+        return try outcome.get()
+    }
+
+    /// The attached session, without attaching one.
+    public func current() -> BridgeSession? {
+        state.withLock { $0.attached }
+    }
+
+    public var isInvalidated: Bool {
+        state.withLock { $0.invalidated }
+    }
+
+    @discardableResult
+    public func invalidate() -> Task<Void, Never> {
+        let session = state.withLock { state -> BridgeSession? in
+            state.invalidated = true
+            defer { state.attached = nil }
+            return state.attached
+        }
+        return Task { await session?.invalidate() }
+    }
+}

package/ios/TerraBridgeCore/StreamRegistry.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// One native stream per subscriber, started on subscribe and cancelled on unsubscribe.
+///
+/// What arrives is already framed, endings included, by the generated `BridgeStreamDispatch`.
+final class StreamRegistry: Sendable {
+    typealias Sink = @Sendable (_ subscriptionId: String, _ message: String) -> Void
+
+    private struct State {
+        var next = 0
+        var tasks: [String: Task<Void, Never>] = [:]
+        var closed = false
+    }
+
+    private let state = Locked(State())
+
+    /// Forwards `source`, already framed with its ending by `BridgeStreamDispatch`, until it ends
+    /// or is cancelled, and answers the id that cancels it.
+    ///
+    /// The task is created under the lock, so its own removal at the end cannot run before its
+    /// insertion - a source that finishes at once would otherwise leave its entry behind forever.
+    func start(sink: @escaping Sink, source: AsyncStream<Data>) -> String {
+        state.withLock { state in
+            state.next += 1
+            let id = "sub-\(state.next)"
+            guard !state.closed else { return id }
+            state.tasks[id] = Task {
+                for await message in source {
+                    // A cancelled source still frames an ending; the subscriber asked for silence.
+                    guard !Task.isCancelled else { break }
+                    sink(id, String(decoding: message, as: UTF8.self))
+                }
+                self.finished(id)
+            }
+            return id
+        }
+    }
+
+    /// An unknown id is ignored: a second unsubscribe is not an error.
+    func cancel(_ id: String) {
+        state.withLock { $0.tasks.removeValue(forKey: id) }?.cancel()
+    }
+
+    /// Cancels everything and starts nothing new, for a host runtime that is going away.
+    func close() {
+        let tasks = state.withLock { state in
+            state.closed = true
+            defer { state.tasks = [:] }
+            return Array(state.tasks.values)
+        }
+        for task in tasks { task.cancel() }
+    }
+
+    var count: Int { state.withLock { $0.tasks.count } }
+
+    private func finished(_ id: String) {
+        state.withLock { _ = $0.tasks.removeValue(forKey: id) }
+    }
+}

package/ios/TerraBridgeCore/TerraBridge.swift

@@ -0,0 +1,122 @@
+import Foundation
+import TerraSDK
+
+/// The process-wide half: the client, and the broker it was built with.
+///
+/// Built once, at launch, by the native bootstrap - before any JavaScript or Dart exists, because
+/// background sync needs a live client then. A runtime that comes and goes (a JS reload, a Flutter
+/// engine) attaches a `BridgeSession` to it and detaches by invalidating that session.
+///
+/// Nothing here may mention a framework: no promise type, no `NSDictionary`, no `FlutterResult`.
+public final class TerraBridge: Sendable {
+    public typealias TokenProvider = @Sendable () async throws -> String
+
+    /// The client, for the bootstrap that registers it with `BackgroundSync`.
+    public let terra: Terra
+
+    let host: any BridgeHost
+    let broker: TokenBroker
+    let deviceZone: @Sendable () -> TimeZone
+
+    /// `client` receives the provider the client must be built with. The broker exists before the
+    /// client because the client captures its provider at construction: a broker made afterwards
+    /// would be one the SDK never asks.
+    public init(
+        host: any BridgeHost,
+        deviceZone: @escaping @Sendable () -> TimeZone = { .current },
+        client: (_ tokenProvider: @escaping TokenProvider) throws -> Terra
+    ) rethrows {
+        let broker = TokenBroker()
+        self.broker = broker
+        self.host = host
+        self.deviceZone = deviceZone
+        self.terra = try client { try await broker.provide() }
+    }
+
+    /// One session per runtime. `emit` receives `(subscriptionId, StreamMessage JSON)`.
+    public func attach(emit: @escaping @Sendable (_ subscriptionId: String, _ message: String) -> Void) -> BridgeSession {
+        BridgeSession(bridge: self, emit: emit)
+    }
+}
+
+/// What a framework layer calls: dispatch, subscribe, unsubscribe, invalidate.
+///
+/// A React Native TurboModule forwards `invoke` to `dispatch` and its emitter to `emit`. A Flutter
+/// `MethodChannel` is `dispatch(call.method, call.arguments)` and an `EventChannel` wraps
+/// `subscribe`.
+public final class BridgeSession: Sendable {
+    private let bridge: TerraBridge
+    private let emit: @Sendable (String, String) -> Void
+    private let subscriptions = StreamRegistry()
+    private let audience = TokenAudience()
+    private let ops: BridgeDispatch
+    private let streams: BridgeStreamDispatch
+
+    init(bridge: TerraBridge, emit: @escaping @Sendable (String, String) -> Void) {
+        self.bridge = bridge
+        self.emit = emit
+        self.ops = BridgeDispatch(ops: TerraBridgeOpsImpl(
+            terra: bridge.terra, host: bridge.host, broker: bridge.broker, audience: audience))
+        self.streams = BridgeStreamDispatch(
+            streams: TerraBridgeStreamsImpl(terra: bridge.terra, audience: audience, deviceZone: bridge.deviceZone),
+            errorPayload: { Rejections.payload(for: $0) })
+    }
+
+    /// A session dropped without `invalidate` still stops its streams: they would otherwise keep
+    /// a source polling for a runtime that is gone.
+    deinit {
+        audience.close()
+        subscriptions.close()
+    }
+
+    /// Runs one op and answers its response JSON. Never throws a raw SDK error: the framework layer
+    /// rejects with `rejection.payload`, so the error table lives here once rather than in each
+    /// wrapper.
+    public func dispatch(op: String, payload: String) async throws(BridgeRejection) -> String {
+        do {
+            let response = try await ops(op: op, payload: Data(payload.utf8))
+            return String(decoding: response, as: UTF8.self)
+        } catch {
+            throw BridgeRejection(payload: Rejections.payload(for: error))
+        }
+    }
+
+    /// Starts one native stream for this subscriber and answers the id that cancels it. Messages
+    /// arrive through `emit` under that id. The source is open before this returns.
+    public func subscribe(stream: String, params: String) async throws(BridgeRejection) -> String {
+        do {
+            let source = try await streams.open(stream: stream, params: Data(params.utf8))
+            return subscriptions.start(sink: emit, source: source)
+        } catch {
+            throw BridgeRejection(payload: Rejections.payload(for: error))
+        }
+    }
+
+    public func unsubscribe(id: String) {
+        subscriptions.cancel(id)
+    }
+
+    /// For a runtime that is going away. The client outlives it, so what is torn down is everything
+    /// that pointed at this runtime: its streams, and the token asks it was sent.
+    public func invalidate() async {
+        audience.close()
+        subscriptions.close()
+        await bridge.broker.invalidate(audience)
+    }
+
+    /// Visible for tests.
+    var liveSubscriptions: Int { subscriptions.count }
+}
+
+/// What the framework layer turns into a rejected promise.
+public struct BridgeRejection: Error, Sendable {
+    public let payload: TerraErrorPayload
+
+    public var code: String { payload.code }
+
+    /// The payload as the wire spells it, for a layer that rejects with a JSON string.
+    public var json: String {
+        (try? String(decoding: BridgeDispatch.makeEncoder().encode(payload), as: UTF8.self))
+            ?? #"{"code":"\#(payload.code)","message":"","retryable":\#(payload.retryable)}"#
+    }
+}

package/ios/TerraBridgeCore/TerraBridgeOpsImpl.swift

@@ -0,0 +1,254 @@
+import Foundation
+@_spi(Bridge) import TerraSDK
+
+/// The hand-written half: one short function per op.
+///
+/// It cannot be incomplete, because `TerraBridgeOps` is generated from the schema and an op added
+/// there stops this compiling. Conversions live in `Conversions`; what is left is the shape of each
+/// call, and the one place Apple's surface differs from the wire's: `sync`, `disconnect` and plans
+/// hang off a `Connection` here rather than off the client.
+struct TerraBridgeOpsImpl: TerraBridgeOps {
+    let terra: Terra
+    let host: any BridgeHost
+    let broker: TokenBroker
+    let audience: TokenAudience
+
+    // MARK: client
+
+    func clientAttach(_ request: Empty) async throws -> BootstrapState {
+        BootstrapState(
+            bootstrapped: true,
+            devId: host.devID,
+            platform: "ios",
+            sdkVersion: TerraSDK.sdkVersion,
+            backgroundRegistered: await host.backgroundRegistered())
+    }
+
+    func clientConnect(_ request: ConnectRequest) async throws -> Connection {
+        let source = try Conversions.source(request.source)
+        let endUser = Conversions.endUser(request.endUser)
+        if let token = request.token {
+            return Conversions.connection(try await terra.connect(source, for: endUser, using: token))
+        }
+        // The client's provider is the broker, so it is never nil, and the SDK's answer for a
+        // revoked link with no provider - `linkRevoked` - would become the broker's "nobody is
+        // listening". So the bridge answers it here, before any link starts.
+        if await !broker.canAnswer, await terra.needsTokenForRevokedLink(source, for: endUser) {
+            throw TerraError.linkRevoked(source)
+        }
+        return Conversions.connection(try await terra.connect(source, for: endUser))
+    }
+
+    func clientConnections(_ request: Empty) async throws -> ConnectionList {
+        ConnectionList(connections: try await terra.connections.map(Conversions.connection))
+    }
+
+    func clientDisconnect(_ request: SourceRequest) async throws -> Empty {
+        try await connection(request.source).disconnect()
+        return Empty()
+    }
+
+    // MARK: token
+
+    func tokenSetProviderPresent(_ request: TokenProviderRequest) async throws -> Empty {
+        await broker.setProviderPresent(request.present, timeoutMs: request.timeoutMs, audience: audience)
+        return Empty()
+    }
+
+    func tokenResolve(_ request: TokenResolveRequest) async throws -> Empty {
+        await broker.resolve(request.requestId, token: request.token)
+        return Empty()
+    }
+
+    func tokenReject(_ request: TokenRejectRequest) async throws -> Empty {
+        await broker.reject(request.requestId, message: request.message)
+        return Empty()
+    }
+
+    // MARK: permissions
+
+    /// HealthKit will not say what was granted for reads, so Apple answers nothing.
+    func permissionsRequest(_ request: PermissionRequest) async throws -> PermissionGrant {
+        _ = try Conversions.source(request.source)
+        try await terra.permissions.request(
+            read: request.read.map(Conversions.category),
+            write: request.write.map(Conversions.category),
+            workouts: request.workouts.map(Conversions.scope))
+        return PermissionGrant()
+    }
+
+    func permissionsStatus(_ request: CategoryRequest) async throws -> StatusResult {
+        _ = try Conversions.source(request.source)
+        return StatusResult(status: Conversions.permissionStatus(
+            await terra.permissions.status(for: Conversions.category(request.category))))
+    }
+
+    func permissionsWriteStatus(_ request: CategoryRequest) async throws -> StatusResult {
+        _ = try Conversions.source(request.source)
+        return StatusResult(status: Conversions.permissionStatus(
+            await terra.permissions.writeStatus(for: Conversions.category(request.category))))
+    }
+
+    func permissionsRequested(_ request: SourceRequest) async throws -> HealthAccess {
+        _ = try Conversions.source(request.source)
+        return Conversions.access(await terra.permissions.requested)
+    }
+
+    // MARK: diagnostics
+
+    func diagnosticsState(_ request: SourceRequest) async throws -> DiagnosticsState {
+        Conversions.diagnosticsState(await terra.diagnostics.state(for: try Conversions.source(request.source)))
+    }
+
+    func diagnosticsLastDelivery(_ request: SourceRequest) async throws -> LastDeliveryResult {
+        let at = await terra.diagnostics.lastDelivery(for: try Conversions.source(request.source))
+        return LastDeliveryResult(at: at.map(BridgeInstant.format))
+    }
+
+    func diagnosticsReport(_ request: SourceRequest) async throws -> SupportReport {
+        try Conversions.report(await terra.diagnostics.report(for: try Conversions.source(request.source)))
+    }
+
+    func diagnosticsSend(_ request: SourceRequest) async throws -> Empty {
+        try await terra.diagnostics.send(for: try Conversions.source(request.source))
+        return Empty()
+    }
+
+    // MARK: background
+
+    func backgroundIsRegistered(_ request: Empty) async throws -> BoolResult {
+        BoolResult(value: await host.backgroundRegistered())
+    }
+
+    // MARK: body
+
+    func bodyHeartRate(_ request: RangeRequest) async throws -> HeartRateList {
+        HeartRateList(samples: try await terra.body.heartRate(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.heartRate))
+    }
+
+    func bodyLogHeartRate(_ request: HeartRateEntryList) async throws -> RecordIdList {
+        ids(try await terra.body.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func bodyLog(_ request: BodyEntryList) async throws -> RecordIdList {
+        ids(try await terra.body.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func bodyDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.body.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: daily
+
+    func dailySteps(_ request: RangeRequest) async throws -> StepCountList {
+        StepCountList(samples: try await terra.daily.steps(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.steps))
+    }
+
+    func dailyLog(_ request: StepEntryList) async throws -> RecordIdList {
+        ids(try await terra.daily.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func dailyDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.daily.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: sleep
+
+    func sleepSegments(_ request: RangeRequest) async throws -> SleepSegmentList {
+        SleepSegmentList(samples: try await terra.sleep.segments(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.segment))
+    }
+
+    func sleepLog(_ request: SleepEntryList) async throws -> RecordIdList {
+        ids(try await terra.sleep.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func sleepDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.sleep.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: activity
+
+    func activityWorkouts(_ request: RangeRequest) async throws -> WorkoutList {
+        WorkoutList(samples: try await terra.activity.workouts(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.workout))
+    }
+
+    func activityLog(_ request: WorkoutEntryList) async throws -> RecordIdList {
+        ids(try await terra.activity.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func activityDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.activity.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: nutrition
+
+    func nutritionLog(_ request: NutritionEntryList) async throws -> RecordIdList {
+        ids(try await terra.nutrition.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func nutritionDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.nutrition.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: planned workouts
+
+    func plannedWorkoutsPlanned(_ request: Empty) async throws -> PlannedWorkoutList {
+        PlannedWorkoutList(workouts: try await connection(nil).workouts.planned().map(Conversions.plannedWorkout))
+    }
+
+    func plannedWorkoutsMarkComplete(_ request: MarkCompleteRequest) async throws -> Empty {
+        let plans = try await connection(nil).workouts
+        if let at = request.at {
+            try await plans.markComplete(id: request.id, at: Conversions.instant(at, at: "$.at"))
+        } else {
+            try await plans.markComplete(id: request.id)
+        }
+        return Empty()
+    }
+
+    func plannedWorkoutsDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await connection(nil).workouts.delete(id: request.id)
+        return Empty()
+    }
+
+    func plannedWorkoutsSchedulingStatus(_ request: Empty) async throws -> WorkoutScheduling {
+        WorkoutScheduling(status: Conversions.schedulingStatus(
+            try await connection(nil).workouts.schedulingStatus()))
+    }
+
+    func plannedWorkoutsRequestScheduling(_ request: Empty) async throws -> WorkoutScheduling {
+        WorkoutScheduling(status: Conversions.schedulingStatus(
+            try await connection(nil).workouts.requestScheduling()))
+    }
+
+    // MARK: -
+
+    /// Apple hangs per-link behaviour on the `Connection`, so an op naming a source finds it first.
+    private func connection(_ wire: Source?) async throws -> TerraSDK.Connection {
+        let source = try Conversions.source(wire)
+        guard let connection = try await terra.connections.first(where: { $0.source == source }) else {
+            throw TerraError.notConnected(source)
+        }
+        return connection
+    }
+
+    /// Each entry converted with its own path, so a bad one is named by index.
+    private func entries<Wire, Entry>(
+        _ wire: [Wire], _ convert: (Wire, String) throws -> Entry
+    ) throws -> [Entry] {
+        try wire.enumerated().map { try convert($1, "$.entries[\($0)]") }
+    }
+
+    private func ids(_ ids: [UUID]) -> RecordIdList {
+        RecordIdList(ids: ids.map(\.uuidString))
+    }
+}