feat: Bridging hooks calls from MAUI (#142)

- Expose hooks for MAUI
- Fix sending internal traces through Customer API

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes hook/span lifecycle handling and tracing client plumbing, and
introduces new thread-safe caching structures; mistakes could cause
missing/duplicated spans or incorrect telemetry attributes.
> 
> **Overview**
> **Adds MAUI hook bridging** by introducing `ObservabilityHookProxy`
(stored on `LDObserve.shared`) and a shared `ObservabilityHookExporter`
used by both the native Swift `ObservabilityHook` and the MAUI bridge.
> 
> **Refactors evaluation tracing** to track in-flight spans by
`evaluationId` (via new FIFO-evicting `BoundedMap`) and centralizes span
start/end + attribute/event emission in the exporter;
`InternalObserve`/`ObservabilityService` now expose `traceClient` for
this path.
> 
> **Improves cross-boundary value passing** with `LDValue`↔Foundation
(`NSObject`/`NSDictionary`/`NSArray`) conversion helpers, and extends
`AtomicDictionary` with synchronous barrier `setValue`/`removeValue`;
adds unit tests for `BoundedMap` and `LDValue` conversions.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
484f8bb. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abelonogov-ld

Sources/Common/AtomicDictionary.swift

@@ -14,11 +14,29 @@ where Key: Hashable, Key: Sendable {
 
   public init() {}
 
+  // Asynchronous barrier write:
+  // callers rely on this mutation being visible after return.
   public subscript(key: Key) -> Value? {
     get { queue.sync { storage[key] }}
     set { queue.async(flags: .barrier) { [weak self] in self?.storage[key] = newValue } }
   }
 
+  public func setValue(_ value: Value?, forKey key: Key) {
+    // Synchronous barrier write:
+    // callers rely on this mutation being visible immediately after return.
+    queue.sync(flags: .barrier) {
+      storage[key] = value
+    }
+  }
+
+  public func removeValue(forKey key: Key) -> Value? {
+    // Synchronous barrier remove:
+    // this acts like an atomic "pop" (read + remove in one critical section).
+    queue.sync(flags: .barrier) {
+      storage.removeValue(forKey: key)
+    }
+  }
+
   public var debugDescription: String {
       return queue.sync { storage.debugDescription }
   }

Sources/Common/BoundedMap.swift

@@ -0,0 +1,58 @@
+import Foundation
+
+/// Thread-safe bounded dictionary with FIFO eviction.
+///
+/// - Insertions beyond `capacity` evict the oldest key/value pair.
+/// - `setValue` and eviction happen atomically in one barrier section.
+public final class BoundedMap<Key, Value>: @unchecked Sendable
+where Key: Hashable, Key: Sendable {
+    private var storage = [Key: Value]()
+    private var insertionOrder = [Key]()
+    private let capacity: Int
+
+    private let queue = DispatchQueue(
+        label: "com.observability.bounded-map.\(UUID().uuidString)",
+        qos: .utility,
+        attributes: .concurrent,
+        autoreleaseFrequency: .inherit,
+        target: .global()
+    )
+
+    public init(capacity: Int) {
+        self.capacity = max(1, capacity)
+    }
+
+    /// Atomically sets a value and optionally evicts the oldest item.
+    /// - Returns: Evicted key/value if capacity overflow occurs, otherwise nil.
+    @discardableResult
+    public func setValue(_ value: Value, forKey key: Key) -> (key: Key, value: Value)? {
+        queue.sync(flags: .barrier) {
+            if storage[key] != nil, let idx = insertionOrder.firstIndex(of: key) {
+                insertionOrder.remove(at: idx)
+            }
+
+            storage[key] = value
+            insertionOrder.append(key)
+
+            guard insertionOrder.count > capacity else { return nil }
+            let evictedKey = insertionOrder.removeFirst()
+            guard let evictedValue = storage.removeValue(forKey: evictedKey) else { return nil }
+            return (evictedKey, evictedValue)
+        }
+    }
+
+    /// Atomically removes and returns the value for a key.
+    public func removeValue(forKey key: Key) -> Value? {
+        queue.sync(flags: .barrier) {
+            let removed = storage.removeValue(forKey: key)
+            if removed != nil, let idx = insertionOrder.firstIndex(of: key) {
+                insertionOrder.remove(at: idx)
+            }
+            return removed
+        }
+    }
+
+    public var count: Int {
+        queue.sync { storage.count }
+    }
+}

Sources/Common/LDValue+Foundation.swift

@@ -0,0 +1,81 @@
+import Foundation
+import LaunchDarkly
+
+/// Converts between Swift LDValue (enum) and Foundation types (NSObject hierarchy)
+/// so values can cross the Obj-C / MAUI boundary without JSON string parsing.
+///
+/// Mapping:
+///   .null             <-> NSNull
+///   .bool(Bool)       <-> NSNumber(value: Bool)
+///   .number(Double)   <-> NSNumber(value: Double)
+///   .string(String)   <-> NSString
+///   .array([...])     <-> NSArray
+///   .object({...})    <-> NSDictionary
+extension LDValue {
+
+    public func toFoundation() -> NSObject {
+        switch self {
+        case .null:
+            return NSNull()
+        case .bool(let b):
+            return NSNumber(value: b)
+        case .number(let d):
+            return NSNumber(value: d)
+        case .string(let s):
+            return s as NSString
+        case .array(let arr):
+            return arr.map { $0.toFoundation() } as NSArray
+        case .object(let dict):
+            let ns = NSMutableDictionary(capacity: dict.count)
+            for (k, v) in dict {
+                ns[k] = v.toFoundation()
+            }
+            return ns
+        }
+    }
+
+    public static func fromFoundation(_ obj: Any?) -> LDValue {
+        guard let obj = obj else { return .null }
+        if obj is NSNull { return .null }
+
+        if let num = obj as? NSNumber {
+            if CFGetTypeID(num) == CFBooleanGetTypeID() {
+                return .bool(num.boolValue)
+            }
+            return .number(num.doubleValue)
+        }
+
+        if let str = obj as? String { return .string(str) }
+
+        if let arr = obj as? [Any] {
+            return .array(arr.map { fromFoundation($0) })
+        }
+
+        if let dict = obj as? [String: Any] {
+            return .object(dict.mapValues { fromFoundation($0) })
+        }
+
+        return .null
+    }
+}
+
+extension Dictionary where Key == String, Value == LDValue {
+
+    public func toFoundation() -> NSDictionary {
+        let ns = NSMutableDictionary(capacity: count)
+        for (k, v) in self {
+            ns[k] = v.toFoundation()
+        }
+        return ns
+    }
+
+    public static func fromFoundation(_ dict: NSDictionary?) -> [String: LDValue]? {
+        guard let dict = dict, dict.count > 0 else { return nil }
+        var result = [String: LDValue]()
+        for (k, v) in dict {
+            guard let key = k as? String else { continue }
+            result[key] = LDValue.fromFoundation(v)
+        }
+        return result
+    }
+}

…aunchDarklyObservability/LDObserve.swift …hDarklyObservability/API/LDObserve.swiftSources/LaunchDarklyObservability/LDObserve.swift renamed to Sources/LaunchDarklyObservability/API/LDObserve.swift Sources/LaunchDarklyObservability/LDObserve.swift renamed to Sources/LaunchDarklyObservability/API/LDObserve.swift

@@ -17,7 +17,9 @@ public final class LDObserve  {
     }
     public static let shared = LDObserve()
     public var context: ObservabilityContext?
-    
+    public var hookProxy: ObservabilityHookProxy?
+    var plugin: Observability?
+
     init(client: Observe = NoOpObservabilityService.shared) {
         self._client = client
     }

…ervability/API/ObjcLDObserveBridge.swift …ability/Bridge/ObjcLDObserveBridge.swiftSources/LaunchDarklyObservability/API/ObjcLDObserveBridge.swift renamed to Sources/LaunchDarklyObservability/Bridge/ObjcLDObserveBridge.swift Sources/LaunchDarklyObservability/API/ObjcLDObserveBridge.swift renamed to Sources/LaunchDarklyObservability/Bridge/ObjcLDObserveBridge.swift

@@ -28,4 +28,5 @@ public final class ObjcLDObserveBridge: NSObject {
 
         LDObserve.shared.recordLog(message: message, severity: sev, attributes: attrs)
     }
+    
 }

Sources/LaunchDarklyObservability/Client/InternalObserve.swift

@@ -1,3 +1,4 @@
 protocol InternalObserve: Observe {
     var logClient: LogsApi { get }
+    var traceClient: TracesApi { get }
 }

Sources/LaunchDarklyObservability/Client/ObservabilityService.swift

@@ -7,6 +7,7 @@ import OSLog
 
 final class ObservabilityService: InternalObserve {
     var logClient: LogsApi { loggerClient }
+    var traceClient: TracesApi { _traceClient }
     private let logger: LogsApi
     private let meter: MetricsApi
     private let tracer: TracesApi
@@ -24,7 +25,7 @@ final class ObservabilityService: InternalObserve {
 
     private let metricsClient: MetricsApi
 
-    private let traceClient: TraceClient
+    private let _traceClient: TraceClient
     private let tracerDecorator: TracerDecorator
 
     private var instruments = [AutoInstrumentation]()
@@ -157,7 +158,7 @@ final class ObservabilityService: InternalObserve {
             options: options.tracesApi,
             tracer: tracerDecorator
         )
-        self.traceClient = traceClient
+        self._traceClient = traceClient
 
         let appTraceClient = AppTraceClient(
             options: options.tracesApi,
@@ -195,7 +196,7 @@ extension ObservabilityService {
             instruments
                 .append(
                     InstrumentationTask<TraceClient>(
-                        instrument: traceClient,
+                        instrument: _traceClient,
                         samplingInterval: autoInstrumentationSamplingInterval
                     ) {
                         await launchTracker.trace(using: $0)

Sources/LaunchDarklyObservability/Plugin/Observability.swift

@@ -54,6 +54,7 @@ public final class Observability: Plugin {
             observabilityService = service
             LDObserve.shared.client = service
             LDObserve.shared.context = service.context
+            LDObserve.shared.plugin = self
 
             if options.isEnabled {
                 service.start()
@@ -64,11 +65,14 @@ public final class Observability: Plugin {
     }
 
     public func getHooks(metadata: EnvironmentMetadata) -> [any Hook] {
-        [ObservabilityHook(plugin: self,
-                         withSpans: true,
-                         withValue: true,
-                         version: options.serviceVersion,
-                         options: options)]
+        let exporter = ObservabilityHookExporter(
+            plugin: self,
+            withSpans: true,
+            withValue: true,
+            options: options
+        )
+        LDObserve.shared.hookProxy = ObservabilityHookProxy(exporter: exporter)
+        return [ObservabilityHook(exporter: exporter)]
     }
 }