@barrysolomon/mobile-react-native 0.1.1-alpha → 0.2.1-alpha

package/ios/OTelMobileCallSink.swift

@@ -1,22 +1,111 @@
 // Production BridgeCallSink for iOS. Forwards RN bridge calls into the
 // existing OTelMobileSDK.OTelMobile facade.
 //
-// This file is compiled ONLY when OTelMobileSDK is linkable. When the RN
-// package is built standalone (CI cold-compile without a host app) the
-// RCTDash0MobileModule falls back to NoopSink.
+// This file is compiled whenever OTelMobileSDK is linkable. In the RN package
+// it is built + unit-tested against the sibling `otel-ios-mobile` SwiftPM
+// package (see Package.swift). When a host app's pod build can't see the SDK
+// at compile time the RCTDash0MobileModule still falls back to NoopSink.
+//
+// ## Testability seam
+//
+// The sink never reaches into a concrete network exporter directly: every
+// span/log/metric goes through OTel-Swift's `Tracer` / `Logger` / `Meter`
+// handles. Those handles are resolved once, at `start(_:)`:
+//
+//   - Production: from a real `OTelMobile.start(config:)` instance, whose
+//     providers are wired to the OTLP/HTTP exporters.
+//   - Tests: injected via `init(telemetryProvider:)` with handles backed by
+//     in-memory / recording exporters, so the sink's real logic (parent
+//     linkage, LRU eviction, severity/kind mapping, attribute coercion,
+//     counter clamping) runs against real OTel-Swift primitives and the
+//     resulting spans/logs/metrics can be asserted on.
+//
+// This keeps the production path byte-for-byte the same while making the
+// whole sink compile + unit-test under `xcodebuild test` in CI.
 
 #if canImport(OTelMobileSDK)
 import Foundation
 import OpenTelemetryApi
 import OTelMobileSDK
 
+/// The OTel-Swift signal handles the sink needs, plus the lifecycle hooks it
+/// must forward (flush/shutdown). Production builds these from a real
+/// `OTelMobile`; tests build them from capturing exporters.
+struct SinkTelemetry {
+    let tracer: Tracer?
+    let logger: Logger?
+    let meter: Meter?
+    /// Synchronous drain of all buffered telemetry. No-op when absent.
+    let forceFlush: () -> Void
+    /// Selective time-window flush in minutes. No-op when absent.
+    let flushWindow: (Int) -> Void
+    /// Release the underlying SDK. No-op when absent.
+    let shutdown: () -> Void
+}
+
+/// Builds a `SinkTelemetry` from a started `OTelMobile`, capturing it so the
+/// flush/shutdown closures route to the real instance. Production seam.
+extension SinkTelemetry {
+    init(otel: OTelMobile) {
+        self.tracer = otel.tracer
+        self.logger = otel.logger
+        self.meter = otel.meter
+        self.forceFlush = { _ = otel.forceFlush() }
+        self.flushWindow = { minutes in
+            Task.detached { _ = await otel.flushWindow(minutes: UInt64(max(0, minutes))) }
+        }
+        // OTelMobile has no explicit teardown; dropping the strong reference
+        // releases its providers. Captured weakly to avoid a retain cycle is
+        // unnecessary because the closure is owned by the sink, not the SDK.
+        self.shutdown = {}
+    }
+}
+
 final class OTelMobileCallSink: BridgeCallSink {
-    private var otel: OTelMobile?
+    /// Resolved at `start(_:)`. `nil` until then (or if start fails / a test
+    /// injected an empty provider), making every emit a safe no-op.
+    private var telemetry: SinkTelemetry?
+
+    /// Test-injection seam: when set, `start(_:)` adopts this telemetry
+    /// instead of building a real `OTelMobile`. Lets unit tests drive the
+    /// sink against capturing exporters while leaving production untouched.
+    private let injectedTelemetry: SinkTelemetry?
+
     private let spanLock = NSLock()
-    private var liveSpans: [String: Span] = [:]
+    /// Upper bound on concurrently-live (started-but-not-ended) spans. A
+    /// misbehaving JS layer that starts spans without ending them must not
+    /// balloon native memory. Matches the historical ~2048 ceiling.
+    static let maxLiveSpans = 2048
+
+    /// O(1) lookup-by-id AND O(1) oldest-eviction. Replaces the previous
+    /// unbounded `[String: Span]` (which leaked on never-ended spans) — and
+    /// avoids the O(n) `firstIndex` scan a naive bounded list would need on
+    /// eviction. All access is serialized under `spanLock`.
+    private let liveSpans: BoundedLiveSpanStore<String, Span>
+
+    /// Production initializer. Builds a real `OTelMobile` lazily in `start(_:)`.
+    init() {
+        self.injectedTelemetry = nil
+        self.liveSpans = BoundedLiveSpanStore(capacity: Self.maxLiveSpans)
+    }
+
+    /// Test initializer. Adopts caller-supplied telemetry (handles backed by
+    /// in-memory exporters) so the sink's logic is exercised end-to-end without
+    /// any network. `capacity` is overridable so eviction tests don't need to
+    /// push 2048 spans to trip the cap.
+    init(telemetry: SinkTelemetry, capacity: Int = OTelMobileCallSink.maxLiveSpans) {
+        self.injectedTelemetry = telemetry
+        self.liveSpans = BoundedLiveSpanStore(capacity: capacity)
+    }
 
     func start(_ config: BridgeStartConfig) {
-        guard otel == nil else { return }
+        guard telemetry == nil else { return }
+
+        // Test path: adopt the injected telemetry, skip building a real SDK.
+        if let injected = injectedTelemetry {
+            telemetry = injected
+            return
+        }
 
         // Dash0 OTLP ingress wants Bearer auth + Dash0-Dataset as explicit
         // headers, not as separate MobileConfig fields. Build them here so
@@ -45,24 +134,44 @@ final class OTelMobileCallSink: BridgeCallSink {
             authToken: config.authToken,
             exportMode: exportMode,
             extraHeaders: extraHeaders,
+            // RN sampling default is .alwaysOn (Loper finding #4): RN manual
+            // spans are root spans with arbitrary names, so the native SDK's
+            // dynamic(0.1) default would silently drop ~90% of a user's first
+            // span — and a dropped iOS span is a non-recording PropagatedSpan
+            // whose end() is a silent no-op. The JS bridge sends always_on
+            // unless the caller opts into sampling; rate-limiting for RN
+            // belongs in the collector.
+            samplingConfig: Self.samplingConfig(from: config.sampling),
             extraResourceAttributes: mergedAttrs
         )
         do {
-            otel = try OTelMobile.start(config: mobileConfig)
+            let otel = try OTelMobile.start(config: mobileConfig)
+            telemetry = SinkTelemetry(otel: otel)
         } catch {
             // Start failure is logged but non-fatal — JS side stays operational
             // and future emitBatch calls become no-ops until a successful start.
-            NSLog("[@dash0/mobile-react-native] OTelMobile.start failed: \(error)")
+            // Do NOT interpolate the full error: it can embed the endpoint URL
+            // (incl. credentials) or auth token. Log a static message + the
+            // error code only, and only when debug logging is enabled.
+            Self.debugLog("OTelMobile.start failed (code \((error as NSError).code))")
         }
     }
 
+    /// Gate diagnostic NSLogs behind a debug flag so production builds don't
+    /// emit potentially sensitive init/auth detail to the device log.
+    private static func debugLog(_ message: @autoclosure () -> String) {
+        #if DEBUG
+        NSLog("[@dash0/mobile-react-native] %@", message())
+        #endif
+    }
+
     func emitLog(
         name: String,
         severity: Int,
         attributes: [String: Any],
         timeUnixNano: UInt64
     ) {
-        guard let logger = otel?.logger else { return }
+        guard let logger = telemetry?.logger else { return }
         var builder = logger.logRecordBuilder()
             .setBody(AttributeValue.string(name))
             .setSeverity(Self.mapSeverity(severity))
@@ -76,22 +185,57 @@ final class OTelMobileCallSink: BridgeCallSink {
 
     func startSpan(
         spanId: String,
+        parentSpanId: String?,
         name: String,
         spanKind: String,
         attributes: [String: Any],
         startTimeUnixNano: UInt64
     ) {
-        guard let tracer = otel?.tracer else { return }
-        let span = tracer.spanBuilder(spanName: name)
+        guard let tracer = telemetry?.tracer else { return }
+
+        // Resolve the parent span (if still live) under the lock, then build
+        // OUTSIDE the lock — never hold spanLock across OTel calls.
+        var parentSpan: Span?
+        if let parentSpanId = parentSpanId {
+            spanLock.lock()
+            parentSpan = liveSpans.value(forKey: parentSpanId)
+            spanLock.unlock()
+        }
+
+        let builder = tracer.spanBuilder(spanName: name)
             .setStartTime(time: Self.dateFromUnixNano(startTimeUnixNano))
-            .setSpanKind(kind: Self.mapSpanKind(spanKind))
-            .startSpan()
+            .setSpanKind(spanKind: Self.mapSpanKind(spanKind))
+        if let parentSpan = parentSpan {
+            // Establish real OTel parent-child linkage so the child inherits
+            // the parent's trace id and records it as `parentSpanId` in
+            // SpanData — this is what stitches the RN-side span tree together
+            // into one trace in Dash0. Also mirror the bridge-supplied id as
+            // an attribute so cross-referencing the JS span id stays possible
+            // even after sampling drops the parent.
+            builder.setParent(parentSpan)
+            if let parentSpanId = parentSpanId {
+                builder.setAttribute(key: "parent.span.id", value: AttributeValue.string(parentSpanId))
+            }
+        }
+        let span = builder.startSpan()
         for (k, v) in Self.toAttributeValues(attributes) {
             span.setAttribute(key: k, value: v)
         }
+
+        // Insert + enforce the LRU cap. Capture any victim under the lock,
+        // then end it OUTSIDE the lock (span.end / status are OTel calls).
+        let evictedTime: UInt64 = startTimeUnixNano
         spanLock.lock()
-        liveSpans[spanId] = span
+        // Inserting at capacity evicts the oldest live span (O(1)). End it so it
+        // is not leaked (the JS side never called endSpan for the orphaned
+        // spanStart). Marked ERROR so the dropped span is visibly attributable
+        // rather than silently OK.
+        let evicted = liveSpans.put(spanId, span)
         spanLock.unlock()
+        if let evicted = evicted {
+            evicted.status = Status.error(description: "span evicted: liveSpans cap (\(liveSpans.capacity)) reached (orphaned spanStart)")
+            evicted.end(time: Self.dateFromUnixNano(evictedTime))
+        }
     }
 
     func endSpan(
@@ -111,9 +255,9 @@ final class OTelMobileCallSink: BridgeCallSink {
         }
         switch status {
         case "OK":
-            span.status = .ok
+            span.status = Status.ok
         case "ERROR":
-            span.status = .error(description: statusMessage ?? "")
+            span.status = Status.error(description: statusMessage ?? "")
         default:
             break
         }
@@ -127,40 +271,51 @@ final class OTelMobileCallSink: BridgeCallSink {
         attributes: [String: Any],
         timeUnixNano: UInt64
     ) {
-        guard let meter = otel?.meter else { return }
+        guard let meter = telemetry?.meter else { return }
         let otelAttrs = Self.toAttributeValues(attributes)
         switch instrumentType {
         case "histogram":
-            meter.histogramBuilder(name: name).build()
-                .record(value: value, attributes: otelAttrs)
+            // `record` is a mutating member on the histogram value type, so the
+            // built instrument must be bound to a `var` before recording.
+            var histogram = meter.histogramBuilder(name: name).build()
+            histogram.record(value: value, attributes: otelAttrs)
         case "gauge":
             // OTel-Swift async gauges require an observer callback; for the
             // bridge's fire-and-forget contract we record a single value via
             // a histogram of size 1 so the last-value aggregation in the
             // backend surfaces the reading. Purpose-built sync gauges land
             // if/when upstream exposes them.
-            meter.histogramBuilder(name: name).build()
-                .record(value: value, attributes: otelAttrs)
+            var gauge = meter.histogramBuilder(name: name).build()
+            gauge.record(value: value, attributes: otelAttrs)
         default:
             // counter — integer values are the common case. Fractional
             // counters aren't expressible through OTel-Swift's long counter,
-            // so truncate and log once if the JS side ever sends a non-int.
-            meter.counterBuilder(name: name).build()
-                .add(value: Int(value), attributes: otelAttrs)
+            // so truncate. `Int(value)` traps on NaN/Inf/out-of-range doubles,
+            // so clamp into Int range first and drop non-finite values.
+            guard value.isFinite else { return }
+            let clamped = value.rounded(.towardZero)
+            let intValue: Int
+            if clamped >= Double(Int.max) {
+                intValue = Int.max
+            } else if clamped <= Double(Int.min) {
+                intValue = Int.min
+            } else {
+                intValue = Int(clamped)
+            }
+            var counter = meter.counterBuilder(name: name).build()
+            counter.add(value: intValue, attributes: otelAttrs)
         }
     }
 
     func flushWindow(minutes: Int) {
-        guard let otel = otel else { return }
-        Task.detached { [otel] in
-            _ = await otel.flushWindow(minutes: UInt64(max(0, minutes)))
-        }
+        telemetry?.flushWindow(minutes)
     }
 
     func shutdown() {
-        otel = nil
+        telemetry?.shutdown()
+        telemetry = nil
         spanLock.lock()
-        liveSpans.removeAll()
+        _ = liveSpans.removeAll()
         spanLock.unlock()
     }
 
@@ -177,12 +332,28 @@ final class OTelMobileCallSink: BridgeCallSink {
     /// to land in Dash0 — the willTerminate observer doesn't fire on
     /// abort().
     func forceFlush() {
-        guard let otel = otel else { return }
-        _ = otel.forceFlush()
+        telemetry?.forceFlush()
     }
 
     // MARK: - Helpers
 
+    /// Translate the bridge sampling config into the SDK's `SamplingConfig`.
+    /// Nil (caller sent nothing) maps to `.alwaysOn` to preserve the RN
+    /// default — see the `samplingConfig:` comment in `start`.
+    private static func samplingConfig(from sampling: BridgeSamplingConfig?) -> SamplingConfig {
+        switch sampling?.strategy {
+        case .none, .alwaysOn:
+            return .alwaysOn()
+        case .alwaysOff:
+            return .alwaysOff()
+        case .dynamic:
+            return .dynamic(
+                normalRate: sampling?.normalRate ?? 0.05,
+                highPriorityRate: sampling?.highPriorityRate ?? 1.0
+            )
+        }
+    }
+
     private static func toAttributeValues(_ raw: [String: Any]) -> [String: AttributeValue] {
         var out: [String: AttributeValue] = [:]
         for (k, v) in raw {
@@ -215,7 +386,7 @@ final class OTelMobileCallSink: BridgeCallSink {
         Date(timeIntervalSince1970: TimeInterval(nano) / 1_000_000_000.0)
     }
 
-    private static func mapSeverity(_ raw: Int) -> Severity {
+    static func mapSeverity(_ raw: Int) -> Severity {
         // OTel severity numbers: 1=TRACE, 5=DEBUG, 9=INFO, 13=WARN, 17=ERROR,
         // 21=FATAL. JS sends the numeric value directly — fall back to INFO
         // when the value is outside the known range so log records never
@@ -231,7 +402,7 @@ final class OTelMobileCallSink: BridgeCallSink {
         }
     }
 
-    private static func mapSpanKind(_ raw: String) -> SpanKind {
+    static func mapSpanKind(_ raw: String) -> SpanKind {
         switch raw {
         case "CLIENT":   return .client
         case "SERVER":   return .server

package/ios/RCTDash0MobileModule.swift

@@ -22,17 +22,25 @@ public final class Dash0MobileModule: NSObject {
     public static var sinkFactory: () -> BridgeCallSink = { NoopSink() }
 
     public static func installSink(_ factory: @escaping () -> BridgeCallSink) {
-        NSLog("[Dash0Mobile] installSink called")
+        Self.debugLog("installSink called")
         sinkFactory = factory
     }
 
     override init() {
         let sink = Dash0MobileModule.sinkFactory()
-        NSLog("[Dash0Mobile] Module init with sink type: \(type(of: sink))")
+        Dash0MobileModule.debugLog("Module init with sink type: \(type(of: sink))")
         self.dispatcher = Dash0MobileBridgeDispatcher(sink: sink)
         super.init()
     }
 
+    /// Gate init/installSink diagnostics behind DEBUG so release builds don't
+    /// leak sink/config detail to the device log.
+    private static func debugLog(_ message: @autoclosure () -> String) {
+        #if DEBUG
+        NSLog("[Dash0Mobile] %@", message())
+        #endif
+    }
+
     // MARK: - For tests
 
     init(dispatcher: Dash0MobileBridgeDispatcher) {

package/ios/Tests/BoundedLiveSpanStoreTests.swift

@@ -0,0 +1,143 @@
+// Tests for the O(1) bounded live-span store used by OTelMobileCallSink.
+//
+// OTelMobileCallSink itself is excluded from this SwiftPM test target (it
+// depends on OTelMobileSDK), so we test the eviction/lookup logic directly on
+// the generic store with a plain value type. This is the same data structure
+// the call sink specializes to `Span`.
+
+import Foundation
+import Testing
+@testable import Dash0MobileReactNative
+
+@Suite("BoundedLiveSpanStore")
+struct BoundedLiveSpanStoreTests {
+
+    @Test("start/end pairing: put then removeValue returns the value")
+    func putThenRemove() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 8)
+        #expect(store.put("a", 1) == nil)
+        #expect(store.count == 1)
+        #expect(store.removeValue(forKey: "a") == 1)
+        #expect(store.count == 0)
+        // Removing again is a safe nil.
+        #expect(store.removeValue(forKey: "a") == nil)
+    }
+
+    @Test("removeValue for absent key returns nil and leaves store intact")
+    func removeAbsent() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 4)
+        store.put("a", 1)
+        #expect(store.removeValue(forKey: "missing") == nil)
+        #expect(store.count == 1)
+    }
+
+    @Test("eviction at capacity drops the OLDEST entry (FIFO)")
+    func evictsOldest() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 3)
+        #expect(store.put("a", 1) == nil)
+        #expect(store.put("b", 2) == nil)
+        #expect(store.put("c", 3) == nil)
+        // Fourth insert evicts the oldest ("a" → 1).
+        #expect(store.put("d", 4) == 1)
+        #expect(store.evictedCount == 1)
+        #expect(store.count == 3)
+        // "a" is gone; b, c, d remain.
+        #expect(store.removeValue(forKey: "a") == nil)
+        #expect(store.removeValue(forKey: "b") == 2)
+        #expect(store.removeValue(forKey: "c") == 3)
+        #expect(store.removeValue(forKey: "d") == 4)
+    }
+
+    @Test("eviction order stays correct after interleaved removes")
+    func evictionAfterRemoves() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 3)
+        store.put("a", 1)
+        store.put("b", 2)
+        store.put("c", 3)
+        // Remove the current oldest explicitly.
+        #expect(store.removeValue(forKey: "a") == 2 - 1) // 1
+        // Now b is oldest. Insert two more; capacity is 3, count is 2 → first
+        // insert fits, second evicts oldest (b).
+        #expect(store.put("d", 4) == nil)   // count 3, no eviction
+        #expect(store.put("e", 5) == 2)     // evicts b
+        #expect(store.removeValue(forKey: "b") == nil)
+        #expect(store.removeValue(forKey: "c") == 3)
+        #expect(store.removeValue(forKey: "d") == 4)
+        #expect(store.removeValue(forKey: "e") == 5)
+    }
+
+    @Test("re-putting an existing key updates value without eviction or reorder")
+    func rePutUpdatesInPlace() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 2)
+        store.put("a", 1)
+        store.put("b", 2)
+        // Overwrite "a" — no eviction, count unchanged, "a" keeps its (oldest)
+        // position so the NEXT insert still evicts "a".
+        #expect(store.put("a", 11) == nil)
+        #expect(store.count == 2)
+        #expect(store.put("c", 3) == 11)   // evicts a (still oldest), now with updated value
+        #expect(store.removeValue(forKey: "a") == nil)
+        #expect(store.removeValue(forKey: "b") == 2)
+        #expect(store.removeValue(forKey: "c") == 3)
+    }
+
+    @Test("removeAll returns all values oldest→newest and empties the store")
+    func removeAllDrains() {
+        let store = BoundedLiveSpanStore<String, Int>(capacity: 8)
+        store.put("a", 1)
+        store.put("b", 2)
+        store.put("c", 3)
+        #expect(store.removeAll() == [1, 2, 3])
+        #expect(store.count == 0)
+        // Store is reusable after removeAll.
+        #expect(store.put("x", 9) == nil)
+        #expect(store.count == 1)
+    }
+
+    @Test("no leak: count never exceeds capacity under sustained inserts")
+    func noLeakUnderChurn() {
+        let cap = 100
+        let store = BoundedLiveSpanStore<Int, Int>(capacity: cap)
+        for i in 0..<10_000 {
+            store.put(i, i)
+            #expect(store.count <= cap)
+        }
+        #expect(store.count == cap)
+        #expect(store.evictedCount == 10_000 - cap)
+        // The surviving keys are the most-recent `cap` insertions.
+        #expect(store.removeValue(forKey: 10_000 - cap) == 10_000 - cap)
+        #expect(store.removeValue(forKey: 10_000 - cap - 1) == nil)
+    }
+
+    @Test("concurrent access via an external lock stays consistent")
+    func concurrentWithExternalLock() async {
+        // Mirrors how OTelMobileCallSink serializes access under spanLock.
+        let box = LockedStore(capacity: 256)
+        await withTaskGroup(of: Void.self) { group in
+            for i in 0..<2000 {
+                group.addTask {
+                    box.put("k\(i % 300)", i)
+                    _ = box.remove("k\(i % 300)")
+                }
+            }
+        }
+        // After all start/remove pairs, the store must not have grown beyond
+        // capacity and must be internally consistent (count == reachable nodes,
+        // enforced by removeAll succeeding without crash).
+        #expect(box.count() <= 256)
+        _ = box.removeAll()
+        #expect(box.count() == 0)
+    }
+
+    /// Tiny lock wrapper so the concurrency test exercises the same
+    /// serialize-under-a-lock pattern the production call sink uses.
+    private final class LockedStore: @unchecked Sendable {
+        private let lock = NSLock()
+        private let store: BoundedLiveSpanStore<String, Int>
+        init(capacity: Int) { store = BoundedLiveSpanStore(capacity: capacity) }
+        func put(_ k: String, _ v: Int) { lock.lock(); store.put(k, v); lock.unlock() }
+        func remove(_ k: String) -> Int? { lock.lock(); defer { lock.unlock() }; return store.removeValue(forKey: k) }
+        func count() -> Int { lock.lock(); defer { lock.unlock() }; return store.count }
+        func removeAll() -> [Int] { lock.lock(); defer { lock.unlock() }; return store.removeAll() }
+    }
+}

package/ios/Tests/Dash0MobileBridgeDispatcherTests.swift

@@ -56,6 +56,69 @@ struct Dash0MobileBridgeDispatcherTests {
         #expect(sink.starts[0].nativeAutoCapture == [])
     }
 
+    // ── start: sampling (Loper finding #4) ─────────────────────────────────
+
+    @Test
+    func start_decodes_alwaysOff_sampling() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+            "sampling": ["strategy": "always_off"],
+        ])
+        #expect(sink.starts[0].sampling == BridgeSamplingConfig(strategy: .alwaysOff))
+    }
+
+    @Test
+    func start_decodes_dynamic_sampling_with_rates() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+            "sampling": ["strategy": "dynamic", "normalRate": 0.1, "highPriorityRate": 1.0],
+        ])
+        #expect(sink.starts[0].sampling == BridgeSamplingConfig(
+            strategy: .dynamic, normalRate: 0.1, highPriorityRate: 1.0
+        ))
+    }
+
+    @Test
+    func start_decodes_alwaysOn_sampling() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+            "sampling": ["strategy": "always_on"],
+        ])
+        #expect(sink.starts[0].sampling == BridgeSamplingConfig(strategy: .alwaysOn))
+    }
+
+    @Test
+    func start_sampling_nil_when_absent() throws {
+        // The JS bridge always sends `sampling`, but the dispatcher must
+        // decode a missing field as nil (the sink then applies the RN
+        // .alwaysOn default).
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: ["serviceName": "s", "endpoint": "https://e"])
+        #expect(sink.starts[0].sampling == nil)
+    }
+
+    @Test
+    func start_unknown_sampling_strategy_falls_back_to_alwaysOn() throws {
+        let sink = RecordingSink()
+        let d = Dash0MobileBridgeDispatcher(sink: sink)
+        try d.start(config: [
+            "serviceName": "s",
+            "endpoint": "https://e",
+            "sampling": ["strategy": "martian"],
+        ])
+        #expect(sink.starts[0].sampling?.strategy == .alwaysOn)
+    }
+
     @Test
     func start_throws_when_serviceName_missing() {
         let sink = RecordingSink()