fix(ios-sdk): propagate STTOptions.language to ONNX decoder via withCString (#404)

* fix(ios-sdk): propagate STTOptions.language to C bridge via withCString

STTOptions.language was silently ignored during transcription, causing
the Whisper ONNX decoder to always default to English regardless of
the language passed by the caller.

Root causes:
- Dangling pointer: (options.language as NSString).utf8String stored a
  pointer into a temporary NSString. ARC released it after the
  assignment, leaving cOptions.language pointing to freed memory before
  the C call. The backend read garbage and fell back to 'en'.
- Incomplete mapping: only language and sample_rate were forwarded to
  rac_stt_options_t. detect_language, enable_punctuation,
  enable_diarization, enable_timestamps, audio_format, and max_speakers
  were silently zero-initialized regardless of caller input.
- processStreamingAudio never set a language field at all.

Fix: add a private STTOptions.withCOptions<T> helper that uses
withCString to guarantee pointer validity for the full duration of the
C call and maps all fields in one place. Apply it to
transcribeWithOptions, transcribeStream, and processStreamingAudio.

Fixes #350

* refactor(ios-sdk): remove duplicate withCOptions, use existing STTTypes.swift impl

The private withCOptions extension in RunAnywhere+STT.swift duplicated
the public STTOptions.withCOptions already defined in STTTypes.swift:127.
Both used withCString for pointer safety and mapped all rac_stt_options_t
fields identically.

Remove the duplicate and update the three call sites to use the public
method's UnsafePointer signature (cOptionsPtr instead of &cOptions).

* fix(ios-sdk): address review comments on processStreamingAudio and STTStreamingContext

- Change processStreamingAudio signature from language: String to
  options: STTOptions = STTOptions() so detectLanguage and all other
  fields are preserved, matching transcribeWithOptions/transcribeStream
- Add missing isLoaded guard to processStreamingAudio before getHandle(),
  surfacing an actionable notInitialized error instead of processingFailed
- Add clarifying comment on sttResult in processStreamingAudio: value is
  intentionally unused as the C layer delivers results via CppEventBridge
- Fix STTStreamingContext data race: replace @unchecked Sendable + bare var
  with OSAllocatedUnfairLock-protected finalText so C callback writes and
  async continuation reads are properly synchronised

* fix(ios-sdk): address final review comments on STTStreamingContext and guard order

- Mark onPartialResult as @sendable so STTStreamingContext's explicit
  Sendable conformance is sound; a non-@sendable stored closure makes
  the conformance unsound under Swift's strict concurrency checking
- Swap guard order in processStreamingAudio to match transcribeWithOptions
  and transcribeStream: getHandle() first, then isLoaded check

Author: ManthanNimodiya

sdk/runanywhere-swift/Sources/RunAnywhere/Public/Extensions/STT/RunAnywhere+STT.swift

@@ -10,6 +10,7 @@
 @preconcurrency import AVFoundation
 import CRACommons
 import Foundation
+import os
 
 // MARK: - STT Operations
 
@@ -77,21 +78,18 @@ public extension RunAnywhere {
         let audioSizeBytes = audioData.count
         let audioLengthSec = estimateAudioLength(dataSize: audioSizeBytes)
 
-        // Build C options
-        var cOptions = rac_stt_options_t()
-        cOptions.language = (options.language as NSString).utf8String
-        cOptions.sample_rate = Int32(options.sampleRate)
-
         // Transcribe (C++ emits events)
         var sttResult = rac_stt_result_t()
-        let transcribeResult = audioData.withUnsafeBytes { audioPtr in
-            rac_stt_component_transcribe(
-                handle,
-                audioPtr.baseAddress,
-                audioData.count,
-                &cOptions,
-                &sttResult
-            )
+        let transcribeResult = options.withCOptions { cOptionsPtr in
+            audioData.withUnsafeBytes { audioPtr in
+                rac_stt_component_transcribe(
+                    handle,
+                    audioPtr.baseAddress,
+                    audioData.count,
+                    cOptionsPtr,
+                    &sttResult
+                )
+            }
         }
 
         guard transcribeResult == RAC_SUCCESS else {
@@ -213,39 +211,36 @@ public extension RunAnywhere {
         let context = STTStreamingContext(onPartialResult: onPartialResult)
         let contextPtr = Unmanaged.passRetained(context).toOpaque()
 
-        // Build C options
-        var cOptions = rac_stt_options_t()
-        cOptions.language = (options.language as NSString).utf8String
-        cOptions.sample_rate = Int32(options.sampleRate)
-
         // Stream transcription with callback
-        let result = audioData.withUnsafeBytes { audioPtr in
-            rac_stt_component_transcribe_stream(
-                handle,
-                audioPtr.baseAddress,
-                audioData.count,
-                &cOptions,
-                { partialText, isFinal, userData in
-                    guard let userData = userData else { return }
-                    let ctx = Unmanaged<STTStreamingContext>.fromOpaque(userData).takeUnretainedValue()
-
-                    let text = partialText.map { String(cString: $0) } ?? ""
-                    let partialResult = STTTranscriptionResult(
-                        transcript: text,
-                        confidence: nil,
-                        timestamps: nil,
-                        language: nil,
-                        alternatives: nil
-                    )
-
-                    ctx.onPartialResult(partialResult)
-
-                    if isFinal == RAC_TRUE {
-                        ctx.finalText = text
-                    }
-                },
-                contextPtr
-            )
+        let result = options.withCOptions { cOptionsPtr in
+            audioData.withUnsafeBytes { audioPtr in
+                rac_stt_component_transcribe_stream(
+                    handle,
+                    audioPtr.baseAddress,
+                    audioData.count,
+                    cOptionsPtr,
+                    { partialText, isFinal, userData in
+                        guard let userData = userData else { return }
+                        let ctx = Unmanaged<STTStreamingContext>.fromOpaque(userData).takeUnretainedValue()
+
+                        let text = partialText.map { String(cString: $0) } ?? ""
+                        let partialResult = STTTranscriptionResult(
+                            transcript: text,
+                            confidence: nil,
+                            timestamps: nil,
+                            language: nil,
+                            alternatives: nil
+                        )
+
+                        ctx.onPartialResult(partialResult)
+
+                        if isFinal == RAC_TRUE {
+                            ctx.finalText = text
+                        }
+                    },
+                    contextPtr
+                )
+            }
         }
 
         // Release context
@@ -276,30 +271,34 @@ public extension RunAnywhere {
     }
 
     /// Process audio samples for streaming transcription
-    /// - Parameter samples: Audio samples
-    static func processStreamingAudio(_ samples: [Float]) async throws {
+    /// - Parameters:
+    ///   - samples: Audio samples
+    ///   - options: Transcription options (default: STTOptions())
+    static func processStreamingAudio(_ samples: [Float], options: STTOptions = STTOptions()) async throws {
         guard isSDKInitialized else {
             throw SDKError.general(.notInitialized, "SDK not initialized")
         }
 
         let handle = try await CppBridge.STT.shared.getHandle()
 
-        var cOptions = rac_stt_options_t()
-        cOptions.sample_rate = Int32(RAC_STT_DEFAULT_SAMPLE_RATE)
-
-        let data = samples.withUnsafeBufferPointer { buffer in
-            Data(buffer: buffer)
+        guard await CppBridge.STT.shared.isLoaded else {
+            throw SDKError.stt(.notInitialized, "STT model not loaded")
         }
 
+        let data = samples.withUnsafeBufferPointer { Data(buffer: $0) }
+
+        // sttResult is intentionally unused: the C layer delivers results via CppEventBridge events.
         var sttResult = rac_stt_result_t()
-        let transcribeResult = data.withUnsafeBytes { audioPtr in
-            rac_stt_component_transcribe(
-                handle,
-                audioPtr.baseAddress,
-                data.count,
-                &cOptions,
-                &sttResult
-            )
+        let transcribeResult = options.withCOptions { cOptionsPtr in
+            data.withUnsafeBytes { audioPtr in
+                rac_stt_component_transcribe(
+                    handle,
+                    audioPtr.baseAddress,
+                    data.count,
+                    cOptionsPtr,
+                    &sttResult
+                )
+            }
         }
 
         if transcribeResult != RAC_SUCCESS {
@@ -325,12 +324,19 @@ public extension RunAnywhere {
 
 // MARK: - Streaming Context Helper
 
-/// Context class for bridging C callbacks to Swift closures
-private final class STTStreamingContext: @unchecked Sendable {
-    let onPartialResult: (STTTranscriptionResult) -> Void
-    var finalText: String = ""
+/// Context class for bridging C callbacks to Swift closures.
+/// `finalText` is written by the C callback thread and read by the async
+/// continuation — protected by OSAllocatedUnfairLock to prevent data races.
+private final class STTStreamingContext: Sendable {
+    let onPartialResult: @Sendable (STTTranscriptionResult) -> Void
+    private let _finalText = OSAllocatedUnfairLock(initialState: "")
+
+    var finalText: String {
+        get { _finalText.withLock { $0 } }
+        set { _finalText.withLock { $0 = newValue } }
+    }
 
-    init(onPartialResult: @escaping (STTTranscriptionResult) -> Void) {
+    init(onPartialResult: @Sendable @escaping (STTTranscriptionResult) -> Void) {
         self.onPartialResult = onPartialResult
     }
 }