@tryterra/react-native 0.0.0-stage → 2.2.1

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/ReadConversions.kt

@@ -0,0 +1,250 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.BloodGlucoseSample
+import co.tryterra.sdk.BloodGlucoseUnit
+import co.tryterra.sdk.BodyMeasurement
+import co.tryterra.sdk.BodyReading
+import co.tryterra.sdk.BodyTemperatureSample
+import co.tryterra.sdk.DayTotal
+import co.tryterra.sdk.HydrationSample
+import co.tryterra.sdk.IntradaySample
+import co.tryterra.sdk.MenstrualEvent
+import co.tryterra.sdk.MenstruationEventSample
+import co.tryterra.sdk.RestingHeartRateSample
+import co.tryterra.sdk.Vo2MaxSample
+import co.tryterra.sdk.WorkoutIntensitySample
+import co.tryterra.sdk.WorkoutRoute
+import co.tryterra.sdk.bridge.generated.BridgeInstant
+import co.tryterra.sdk.health.StoreAvailability
+import co.tryterra.sdk.bridge.generated.BloodGlucoseUnit as WireGlucoseUnit
+import co.tryterra.sdk.bridge.generated.BodyMetric as WireBodyMetric
+import co.tryterra.sdk.bridge.generated.BodyReading as WireBodyReading
+import co.tryterra.sdk.bridge.generated.BodyReadingKind as WireBodyReadingKind
+import co.tryterra.sdk.bridge.generated.BodyTemperatureMetric as WireTemperatureMetric
+import co.tryterra.sdk.bridge.generated.DayTotal as WireDayTotal
+import co.tryterra.sdk.bridge.generated.DayTotalMetric as WireDayTotalMetric
+import co.tryterra.sdk.bridge.generated.GlucoseMealTime as WireMealTime
+import co.tryterra.sdk.bridge.generated.GlucoseSpecimen as WireSpecimen
+import co.tryterra.sdk.bridge.generated.HeartRateVariabilityMetric as WireVariabilityMetric
+import co.tryterra.sdk.bridge.generated.HydrationSample as WireHydrationSample
+import co.tryterra.sdk.bridge.generated.IntradayMetric as WireIntradayMetric
+import co.tryterra.sdk.bridge.generated.IntradaySample as WireIntradaySample
+import co.tryterra.sdk.bridge.generated.MenstrualEvent as WireMenstrualEvent
+import co.tryterra.sdk.bridge.generated.MenstrualEventKind as WireEventKind
+import co.tryterra.sdk.bridge.generated.RestingHeartRateSample as WireRestingHeartRateSample
+import co.tryterra.sdk.bridge.generated.RoutePoint as WireRoutePoint
+import co.tryterra.sdk.bridge.generated.StoreAvailability as WireStoreAvailability
+import co.tryterra.sdk.bridge.generated.VO2MaxTestType as WireTestType
+import co.tryterra.sdk.bridge.generated.WorkoutIntensityMetric as WireIntensityMetric
+import co.tryterra.sdk.bridge.generated.WorkoutIntensitySample as WireIntensitySample
+import co.tryterra.sdk.bridge.generated.WorkoutRoute as WireWorkoutRoute
+
+/**
+ * The reads that close the rest of the 1.x local-read gap, between the SDK's types and the wire's.
+ *
+ * Apart from [Conversions] only because there are many of them, and under its rules: every `when`
+ * is exhaustive with no `else`, so a case added on either side stops the build here, and a case the
+ * read never returns maps to null and is dropped rather than sent under a neighbour's name.
+ */
+internal object ReadConversions {
+
+    /** Null for the metrics `daily.totals` leaves out, which the read never hands over. */
+    fun dayTotalMetric(metric: DayTotal.Metric): WireDayTotalMetric? = when (metric) {
+        DayTotal.Metric.DISTANCE_WALKING_RUNNING -> WireDayTotalMetric.DISTANCE_WALKING_RUNNING
+        DayTotal.Metric.DISTANCE_CYCLING -> WireDayTotalMetric.DISTANCE_CYCLING
+        DayTotal.Metric.DISTANCE_SWIMMING -> WireDayTotalMetric.DISTANCE_SWIMMING
+        DayTotal.Metric.DISTANCE_WHEELCHAIR -> WireDayTotalMetric.DISTANCE_WHEELCHAIR
+        DayTotal.Metric.ACTIVE_ENERGY_BURNED -> WireDayTotalMetric.ACTIVE_ENERGY_BURNED
+        DayTotal.Metric.BASAL_ENERGY_BURNED -> WireDayTotalMetric.BASAL_ENERGY_BURNED
+        DayTotal.Metric.FLIGHTS_CLIMBED -> WireDayTotalMetric.FLIGHTS_CLIMBED
+        DayTotal.Metric.STEPS, DayTotal.Metric.SWIMMING_STROKE_COUNT -> null
+    }
+
+    fun dayTotal(total: DayTotal): WireDayTotal? = dayTotalMetric(total.metric)?.let {
+        WireDayTotal(
+            metric = it,
+            start = BridgeInstant.format(total.interval.start),
+            end = BridgeInstant.format(total.interval.end),
+            value = total.value,
+            unit = total.unit,
+            timeZone = total.timeZone?.id,
+        )
+    }
+
+    fun intradayMetric(metric: IntradaySample.Metric): WireIntradayMetric = when (metric) {
+        IntradaySample.Metric.ACTIVE_ENERGY -> WireIntradayMetric.ACTIVE_ENERGY
+        IntradaySample.Metric.DISTANCE -> WireIntradayMetric.DISTANCE
+        IntradaySample.Metric.FLOORS_CLIMBED -> WireIntradayMetric.FLOORS_CLIMBED
+    }
+
+    fun intraday(sample: IntradaySample): WireIntradaySample = WireIntradaySample(
+        id = sample.id.value,
+        metric = intradayMetric(sample.metric),
+        start = BridgeInstant.format(sample.interval.start),
+        end = BridgeInstant.format(sample.interval.end),
+        value = sample.value,
+        source = Conversions.sampleSource(sample.source),
+        userEntered = sample.userEntered,
+        timeZone = sample.timeZone?.id,
+    )
+
+    fun restingHeartRate(sample: RestingHeartRateSample): WireRestingHeartRateSample = WireRestingHeartRateSample(
+        id = sample.id.value,
+        start = BridgeInstant.format(sample.interval.start),
+        end = BridgeInstant.format(sample.interval.end),
+        beatsPerMinute = sample.beatsPerMinute,
+        source = Conversions.sampleSource(sample.source),
+        userEntered = sample.userEntered,
+        timeZone = sample.timeZone?.id,
+    )
+
+    /** Null for the three `body.readings` leaves out. */
+    fun bodyMetric(metric: BodyMeasurement.Metric): WireBodyMetric? = when (metric) {
+        BodyMeasurement.Metric.WEIGHT -> WireBodyMetric.WEIGHT
+        BodyMeasurement.Metric.HEIGHT -> WireBodyMetric.HEIGHT
+        BodyMeasurement.Metric.BODY_FAT_PERCENTAGE -> WireBodyMetric.BODY_FAT_PERCENTAGE
+        BodyMeasurement.Metric.LEAN_BODY_MASS -> WireBodyMetric.LEAN_BODY_MASS
+        BodyMeasurement.Metric.BONE_MASS,
+        BodyMeasurement.Metric.BODY_WATER_MASS,
+        BodyMeasurement.Metric.BASAL_METABOLIC_RATE,
+        -> null
+    }
+
+    fun glucoseUnit(unit: BloodGlucoseUnit): WireGlucoseUnit = when (unit) {
+        BloodGlucoseUnit.MILLIGRAMS_PER_DECILITRE -> WireGlucoseUnit.MILLIGRAMS_PER_DECILITRE
+        BloodGlucoseUnit.MILLIMOLES_PER_LITRE -> WireGlucoseUnit.MILLIMOLES_PER_LITRE
+    }
+
+    fun mealTime(time: BloodGlucoseSample.MealTime): WireMealTime = when (time) {
+        BloodGlucoseSample.MealTime.PREPRANDIAL -> WireMealTime.PREPRANDIAL
+        BloodGlucoseSample.MealTime.POSTPRANDIAL -> WireMealTime.POSTPRANDIAL
+        BloodGlucoseSample.MealTime.UNKNOWN -> WireMealTime.UNKNOWN
+    }
+
+    fun specimen(specimen: BloodGlucoseSample.Specimen): WireSpecimen = when (specimen) {
+        BloodGlucoseSample.Specimen.CAPILLARY -> WireSpecimen.CAPILLARY
+        BloodGlucoseSample.Specimen.INTERSTITIAL -> WireSpecimen.INTERSTITIAL
+        BloodGlucoseSample.Specimen.PLASMA -> WireSpecimen.PLASMA
+        BloodGlucoseSample.Specimen.SERUM -> WireSpecimen.SERUM
+        BloodGlucoseSample.Specimen.TEARS -> WireSpecimen.TEARS
+        BloodGlucoseSample.Specimen.WHOLE_BLOOD -> WireSpecimen.WHOLE_BLOOD
+        BloodGlucoseSample.Specimen.UNKNOWN -> WireSpecimen.UNKNOWN
+    }
+
+    fun temperatureMetric(metric: BodyTemperatureSample.Metric): WireTemperatureMetric = when (metric) {
+        BodyTemperatureSample.Metric.BODY -> WireTemperatureMetric.BODY
+        BodyTemperatureSample.Metric.BASAL -> WireTemperatureMetric.BASAL
+        BodyTemperatureSample.Metric.SKIN -> WireTemperatureMetric.SKIN
+    }
+
+    fun testType(type: Vo2MaxSample.TestType): WireTestType = when (type) {
+        Vo2MaxSample.TestType.MAX_EXERCISE -> WireTestType.MAX_EXERCISE
+        Vo2MaxSample.TestType.PREDICTED_SUB_MAX_EXERCISE -> WireTestType.PREDICTED_SUB_MAX_EXERCISE
+        Vo2MaxSample.TestType.PREDICTED_NON_EXERCISE -> WireTestType.PREDICTED_NON_EXERCISE
+    }
+
+    fun bodyReadingKind(kind: BodyReading.Kind): WireBodyReadingKind? = when (kind) {
+        is BodyReading.Kind.Measurement -> bodyMetric(kind.metric)?.let { WireBodyReadingKind.Measurement(it, kind.value) }
+        is BodyReading.Kind.BloodPressure ->
+            WireBodyReadingKind.BloodPressure(kind.systolicMillimetersOfMercury, kind.diastolicMillimetersOfMercury)
+        is BodyReading.Kind.BloodGlucose -> WireBodyReadingKind.BloodGlucose(
+            value = kind.value,
+            unit = glucoseUnit(kind.unit),
+            mealTime = kind.mealTime?.let(::mealTime),
+            specimen = kind.specimen?.let(::specimen),
+        )
+        is BodyReading.Kind.OxygenSaturation -> WireBodyReadingKind.OxygenSaturation(kind.fraction)
+        is BodyReading.Kind.Temperature -> WireBodyReadingKind.Temperature(temperatureMetric(kind.metric), kind.celsius)
+        // RMSSD is the only statistic Health Connect records.
+        is BodyReading.Kind.HeartRateVariability ->
+            WireBodyReadingKind.HeartRateVariability(WireVariabilityMetric.RMSSD, kind.rmssdMilliseconds)
+        is BodyReading.Kind.RespiratoryRate -> WireBodyReadingKind.RespiratoryRate(kind.breathsPerMinute)
+        is BodyReading.Kind.Vo2Max ->
+            WireBodyReadingKind.Vo2Max(kind.millilitresPerKilogramPerMinute, kind.testType?.let(::testType))
+    }
+
+    fun bodyReading(reading: BodyReading): WireBodyReading? = bodyReadingKind(reading.kind)?.let {
+        WireBodyReading(
+            id = reading.id.value,
+            kind = it,
+            start = BridgeInstant.format(reading.interval.start),
+            end = BridgeInstant.format(reading.interval.end),
+            source = Conversions.sampleSource(reading.source),
+            userEntered = reading.userEntered,
+            timeZone = reading.timeZone?.id,
+        )
+    }
+
+    fun route(route: WorkoutRoute): WireWorkoutRoute = WireWorkoutRoute(
+        id = route.id.value,
+        workoutId = route.workoutId.value,
+        start = BridgeInstant.format(route.interval.start),
+        end = BridgeInstant.format(route.interval.end),
+        points = route.points.map { WireRoutePoint(BridgeInstant.format(it.time), it.latitude, it.longitude) },
+        source = Conversions.sampleSource(route.source),
+        timeZone = route.timeZone?.id,
+    )
+
+    fun intensityMetric(metric: WorkoutIntensitySample.Metric): WireIntensityMetric = when (metric) {
+        WorkoutIntensitySample.Metric.SPEED -> WireIntensityMetric.SPEED
+        WorkoutIntensitySample.Metric.POWER -> WireIntensityMetric.POWER
+        WorkoutIntensitySample.Metric.CADENCE -> WireIntensityMetric.CADENCE
+    }
+
+    /** An instant on Health Connect, so both ends are its time, and no workout it could name. */
+    fun intensity(sample: WorkoutIntensitySample): WireIntensitySample = WireIntensitySample(
+        id = sample.id.value,
+        metric = intensityMetric(sample.metric),
+        workoutId = null,
+        start = BridgeInstant.format(sample.time),
+        end = BridgeInstant.format(sample.time),
+        value = sample.value,
+        source = Conversions.sampleSource(sample.source),
+        userEntered = sample.userEntered,
+        timeZone = sample.timeZone?.id,
+    )
+
+    fun hydration(sample: HydrationSample): WireHydrationSample = WireHydrationSample(
+        id = sample.id.value,
+        start = BridgeInstant.format(sample.interval.start),
+        end = BridgeInstant.format(sample.interval.end),
+        millilitres = sample.millilitres,
+        source = Conversions.sampleSource(sample.source),
+        userEntered = sample.userEntered,
+        timeZone = sample.timeZone?.id,
+    )
+
+    /**
+     * Which types a partner policy refuses, and which feature is missing, stay in the native report:
+     * the wire names the reason, and the remedy a wrapper app can offer is the same either way.
+     */
+    fun availability(availability: StoreAvailability): WireStoreAvailability = when (availability) {
+        StoreAvailability.Available -> WireStoreAvailability.Available
+        StoreAvailability.ModuleMissing -> WireStoreAvailability.ModuleMissing
+        StoreAvailability.ProviderAppMissing -> WireStoreAvailability.ProviderAppMissing
+        is StoreAvailability.ProviderAppTooOld -> WireStoreAvailability.ProviderAppTooOld(availability.installed)
+        is StoreAvailability.PartnerPolicyMissing -> WireStoreAvailability.PartnerPolicyMissing
+        is StoreAvailability.FeatureUnavailable -> WireStoreAvailability.FeatureUnavailable
+    }
+
+    /** Null for sexual activity, which `menstruation.events` leaves out. */
+    fun eventKind(event: MenstruationEventSample.Event): WireEventKind? = when (event) {
+        MenstruationEventSample.Event.INTERMENSTRUAL_BLEEDING -> WireEventKind.INTERMENSTRUAL_BLEEDING
+        MenstruationEventSample.Event.OVULATION_TEST -> WireEventKind.OVULATION_TEST
+        MenstruationEventSample.Event.CERVICAL_MUCUS -> WireEventKind.CERVICAL_MUCUS
+        MenstruationEventSample.Event.SEXUAL_ACTIVITY -> null
+    }
+
+    fun menstrualEvent(event: MenstrualEvent): WireMenstrualEvent? = eventKind(event.event)?.let {
+        WireMenstrualEvent(
+            id = event.id.value,
+            kind = it,
+            time = BridgeInstant.format(event.time),
+            value = event.value?.wire,
+            storeIdentifier = event.storeIdentifier,
+            source = Conversions.sampleSource(event.source),
+            userEntered = event.userEntered,
+            timeZone = event.timeZone?.id,
+        )
+    }
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/Rejections.kt

@@ -0,0 +1,150 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.NetworkFailure
+import co.tryterra.sdk.TerraError
+import co.tryterra.sdk.bridge.generated.BridgeError
+import co.tryterra.sdk.bridge.generated.Source
+import co.tryterra.sdk.bridge.generated.TerraErrorPayload
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+/**
+ * How a thrown error becomes something a caller in another language can switch on.
+ *
+ * The code comes from the SDK - [TerraError.code] is the vocabulary in `docs/sdk-reference.md`, and
+ * the surface asserts this module speaks exactly it - so there is no mapping table here to drift.
+ * What this file owns is the *detail bag*: which pieces of an error's associated values are safe to
+ * send, and which are not.
+ *
+ * Nothing here may put a health value in `details`. An error reaches a customer's crash reporter and
+ * their logs, so the bag carries identifiers, counts and reasons, never a sample.
+ */
+internal object Rejections {
+
+    /** The payload for any throwable, including one that is not a [TerraError]. */
+    fun of(thrown: Throwable): TerraErrorPayload = when (thrown) {
+        is TerraError -> ofTerraError(thrown)
+        is BridgeError -> TerraErrorPayload(
+            code = thrown.code,
+            retryable = thrown.isRetryable,
+            message = thrown.message ?: thrown.code,
+            details = bridgeDetails(thrown),
+        )
+        else -> TerraErrorPayload(
+            code = "platform",
+            retryable = false,
+            message = "a platform call failed (${thrown::class.java.name})",
+        )
+    }
+
+    private fun ofTerraError(error: TerraError): TerraErrorPayload = TerraErrorPayload(
+        code = error.code,
+        retryable = error.isRetryable,
+        message = message(error),
+        source = sourceOf(error),
+        details = details(error),
+    )
+
+    /**
+     * The text that crosses, which is not always the exception's own.
+     *
+     * Two cases wrap a throwable this SDK did not raise, and `Exception.message` embeds it: a
+     * platform failure's comes from whatever library was reading health records, and a token
+     * provider's is as likely to carry the token it was minting as to describe the failure.
+     * Dropping the details bag for those was not enough while the message still carried the same
+     * text, which is what the test that found this asserts.
+     */
+    private fun message(error: TerraError): String = when (error) {
+        is TerraError.TokenProviderFailed -> "the host's token provider failed"
+        is TerraError.Platform -> "a platform call failed"
+        else -> error.message ?: error.code
+    }
+
+    /** Only the cases that carry one: a default here would be a claim about where a failure happened. */
+    private fun sourceOf(error: TerraError): Source? = when (error) {
+        is TerraError.NotConnected -> wire(error.source)
+        is TerraError.LinkRevoked -> wire(error.source)
+        is TerraError.DevIdMismatch -> wire(error.source)
+        is TerraError.LinkAlreadyRunning -> wire(error.source)
+        is TerraError.ReadQuotaExceeded -> wire(error.source)
+        else -> null
+    }
+
+    private fun wire(source: co.tryterra.sdk.Source): Source = when (source) {
+        co.tryterra.sdk.Source.HEALTH -> Source.HEALTH
+        co.tryterra.sdk.Source.SAMSUNG_HEALTH -> Source.SAMSUNG_HEALTH
+    }
+
+    /**
+     * Exhaustive over the sealed hierarchy with no `else`, which is the point.
+     *
+     * A case added to [TerraError] stops this module compiling until someone decides what, if
+     * anything, of it is safe to send. An `else` here would answer that question with silence.
+     */
+    private fun details(error: TerraError): JsonObject? = when (error) {
+        is TerraError.HealthDataUnavailable -> obj("availability" to JsonPrimitive(error.reason::class.java.simpleName))
+        is TerraError.PermissionDenied -> obj("category" to JsonPrimitive(error.category.name.lowercase()))
+        is TerraError.RouteAwaitingConverter -> obj("dataType" to JsonPrimitive(error.dataType.wire))
+        is TerraError.SyncAlreadyRunning -> obj("dataType" to JsonPrimitive(error.dataType.wire))
+        is TerraError.SampleNotFound -> obj("id" to JsonPrimitive(error.id.value))
+        is TerraError.DeviceKeyUnavailable -> obj("reason" to JsonPrimitive(error.reason))
+        // The cause travels as a code: a nested throwable carries a stack and a message.
+        is TerraError.RollbackIncomplete -> obj(
+            "remaining" to JsonPrimitive(error.remaining.size),
+            "cause" to JsonPrimitive(error.underlying.code),
+        )
+        is TerraError.DistanceNotAttributable -> obj(
+            "activity" to JsonPrimitive(co.tryterra.sdk.WorkoutActivity.reportName(error.activity)),
+        )
+        // No message. The host's own provider threw, and the text it chose is as likely to contain
+        // the token it was minting as it is to describe the failure - `IllegalStateException(
+        // "token=...")` is not a hypothetical. The host already knows why its provider failed; what
+        // it needs from here is the code.
+        is TerraError.TokenProviderFailed -> null
+        // No message, for the same reason with a different source. A platform failure's text comes
+        // from whatever library raised it, which on this path has been reading health records.
+        is TerraError.Platform -> null
+        is TerraError.Network -> networkDetails(error.failure)
+
+        is TerraError.NotConnected,
+        is TerraError.LinkRevoked,
+        is TerraError.DevIdMismatch,
+        is TerraError.LinkAlreadyRunning,
+        is TerraError.ReadQuotaExceeded,
+        -> null
+
+        TerraError.TokenRejected,
+        TerraError.TokenUnavailable,
+        TerraError.SignatureRejected,
+        TerraError.ClockSkewed,
+        TerraError.UserLimitReached,
+        TerraError.LinkConflict,
+        TerraError.UpgradeRequired,
+        TerraError.StoreLocked,
+        TerraError.StoreUnreadable,
+        TerraError.DeadlineExceeded,
+        TerraError.AuthorizationNotDetermined,
+        TerraError.BloodPressureIncomplete,
+        TerraError.AuthorizationUnavailableInExtension,
+        -> null
+    }
+
+    private fun networkDetails(failure: NetworkFailure): JsonObject? = when (failure) {
+        is NetworkFailure.ServerError -> obj("status" to JsonPrimitive(failure.status))
+        is NetworkFailure.Throttled -> failure.retryAfterSeconds?.let { obj("retryAfterSeconds" to JsonPrimitive(it)) }
+        // The IOException's message names a host and sometimes a path; the code alone is the signal.
+        is NetworkFailure.Transport -> null
+        NetworkFailure.MalformedResponse -> null
+    }
+
+    private fun bridgeDetails(error: BridgeError): JsonObject? = when (error) {
+        is BridgeError.NotBootstrapped -> obj("line" to JsonPrimitive(error.line))
+        is BridgeError.UnsupportedOnPlatform -> obj("op" to JsonPrimitive(error.op))
+        is BridgeError.TokenTimeout -> obj("timeoutMs" to JsonPrimitive(error.timeoutMs))
+        is BridgeError.InvalidPayload -> obj("path" to JsonPrimitive(error.path))
+        BridgeError.NoActivity -> null
+        BridgeError.PermissionSheetUnavailable -> null
+    }
+
+    private fun obj(vararg pairs: Pair<String, JsonPrimitive>): JsonObject = JsonObject(pairs.toMap())
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/StreamRegistry.kt

@@ -0,0 +1,77 @@
+package co.tryterra.sdk.bridge
+
+import java.util.concurrent.atomic.AtomicLong
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.launch
+
+/**
+ * One native stream per subscriber, started on subscribe and cancelled on unsubscribe.
+ *
+ * Sharing one collection would be cheaper and wrong: `changes()` polls while it is collected, so a
+ * shared stream keeps polling for a subscriber that has gone away, and that costs the user's
+ * battery. [invalidate] is the other half of the same rule, for a host runtime that reloads.
+ *
+ * Messages arrive fully framed by the generated `BridgeStreamDispatch`, endings included, so what
+ * this owns is only the lifetime of each collection.
+ */
+internal class StreamRegistry(private val scope: CoroutineScope) {
+
+    /**
+     * Guards [jobs], [closed] and every delivery, so subscribe, teardown and a message in flight
+     * are ordered by one lock: nothing is admitted or handed on once [invalidate] returns.
+     */
+    private val gate = Any()
+    private val jobs = HashMap<String, Job>()
+    private var closed: Boolean = false
+    private val nextId = AtomicLong(0)
+
+    /**
+     * Starts [messages] and sends each one to [sink].
+     *
+     * Returns the id the host cancels with. The id is minted here rather than supplied, so two
+     * subscriptions to the same stream cannot collide on a name the host chose.
+     */
+    fun subscribe(messages: Flow<String>, sink: (String, String) -> Unit): String {
+        val id = "sub-${nextId.incrementAndGet()}"
+        val job = scope.launch(start = CoroutineStart.LAZY) {
+            messages.collect { message -> deliver(id, message, sink) }
+        }
+        val admitted = synchronized(gate) {
+            if (!closed) jobs[id] = job
+            !closed
+        }
+        if (!admitted) {
+            job.cancel()
+            return id
+        }
+        job.invokeOnCompletion { synchronized(gate) { jobs.remove(id) } }
+        job.start()
+        return id
+    }
+
+    /** Cancels one subscription. An unknown id is ignored: a double unsubscribe is not an error. */
+    fun unsubscribe(id: String) {
+        synchronized(gate) { jobs.remove(id) }?.cancel()
+    }
+
+    /** Cancels every subscription, for a host runtime that is going away, and admits no later one. */
+    fun invalidate() {
+        val outstanding = synchronized(gate) {
+            closed = true
+            jobs.values.toList().also { jobs.clear() }
+        }
+        outstanding.forEach { it.cancel() }
+    }
+
+    /** Visible for tests: how many subscriptions are live. */
+    fun count(): Int = synchronized(gate) { jobs.size }
+
+    private fun deliver(id: String, message: String, sink: (String, String) -> Unit) {
+        synchronized(gate) {
+            if (!closed && id in jobs) sink(id, message)
+        }
+    }
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/TerraBridge.kt

@@ -0,0 +1,86 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.Terra
+import co.tryterra.sdk.bridge.generated.BridgeDispatch
+import co.tryterra.sdk.bridge.generated.BridgeStreamDispatch
+import co.tryterra.sdk.bridge.generated.TerraErrorPayload
+import java.time.ZoneId
+import kotlinx.coroutines.CoroutineScope
+
+/**
+ * The whole public surface of this module: four calls, and none of them mentions a framework.
+ *
+ * A React Native TurboModule forwards `invoke` to [dispatch] and its event emitter to [subscribe].
+ * A Flutter `MethodChannel` handler is `dispatch(call.method, call.arguments)` and an `EventChannel`
+ * wraps [subscribe]. Nothing above this line may leak below it - no `ReadableMap`, no promise type,
+ * no `MethodCall` - because the second wrapper is supposed to be an emitter and a shell, not a
+ * second bridge.
+ *
+ * One per host runtime. The client and the [tokens] broker outlive a reload and are shared; this
+ * object is what a runtime attaches with, and [invalidate] tears down only what it started.
+ *
+ * @param tokens the broker whose `provide` the client was built with. A different one would be a
+ * broker nobody asks, and every `token.*` op would answer requests that never come.
+ */
+public class TerraBridge(
+    terra: Terra,
+    tokens: TokenBroker,
+    host: BridgeHost,
+    scope: CoroutineScope,
+    deviceZone: ZoneId = ZoneId.systemDefault(),
+    /** Receives `(subscriptionId, StreamMessage JSON)`. The framework layer forwards it to its own emitter. */
+    private val emit: (String, String) -> Unit,
+) {
+    private val session = tokens.session()
+    private val ops = BridgeDispatch(TerraBridgeOpsImpl(terra, host, session))
+    private val streams = BridgeStreamDispatch(TerraBridgeStreamsImpl(terra, session, deviceZone), Rejections::of)
+    private val registry = StreamRegistry(scope)
+
+    /**
+     * Runs one op and answers its response JSON.
+     *
+     * Throws [BridgeRejection], never a raw SDK error: the framework layer rejects a promise with a
+     * code and a detail bag, and asking it to translate a `TerraError` would put the error table in
+     * the RN module and again in the Flutter plugin.
+     */
+    public suspend fun dispatch(op: String, payload: String): String = try {
+        ops.dispatch(op, payload)
+    } catch (thrown: Throwable) {
+        if (thrown is kotlinx.coroutines.CancellationException) throw thrown
+        throw BridgeRejection(Rejections.of(thrown))
+    }
+
+    /**
+     * Starts one stream and answers the id that cancels it.
+     *
+     * Every subscription gets its own native stream. The SDK's `changes()` polls while it is
+     * collected, so a shared one would keep polling for a subscriber that had gone away.
+     */
+    public fun subscribe(stream: String, params: String): String {
+        val messages = try {
+            streams.open(stream, params)
+        } catch (thrown: Throwable) {
+            throw BridgeRejection(Rejections.of(thrown))
+        }
+        return registry.subscribe(messages, emit)
+    }
+
+    public fun unsubscribe(id: String) {
+        registry.unsubscribe(id)
+    }
+
+    /**
+     * For a host runtime that is going away: a JavaScript reload, or a Flutter engine detaching.
+     *
+     * The native client outlives it and must not be rebuilt, so what is torn down is everything
+     * this runtime started - its subscriptions and its pending token asks - and nothing a
+     * replacement runtime has started since.
+     */
+    public fun invalidate() {
+        registry.invalidate()
+        session.close()
+    }
+
+    /** What the framework layer turns into a rejected promise. */
+    public class BridgeRejection(public val payload: TerraErrorPayload) : Exception(payload.message)
+}