@hasna/recordings 0.2.14 → 0.3.2

package/src/native/Recordings/RecordingsTests/RealtimeSettleBenchmark.swift

@@ -0,0 +1,200 @@
+import Foundation
+import Testing
+@testable import RecordingsLib
+
+// MARK: - Realtime settlement benchmark (opt-in, network-bound)
+
+/// Measures how long real OpenAI realtime sessions take to settle after release —
+/// the number the settlement budget in `RecordingEngine` is calibrated against.
+///
+/// This is a live-network benchmark, not a unit test: it opens real realtime
+/// transcription sessions with the machine's configured API key and paces real PCM
+/// through them exactly like the capture pipeline does (4,800-byte chunks every
+/// 100 ms, a periodic commit every 900 ms). It never writes to the production
+/// recordings home — client logs go to a temporary directory.
+///
+/// Disabled unless RECORDINGS_BENCH_REALTIME=1. Configuration:
+///   RECORDINGS_BENCH_WAVS             colon-separated 24 kHz/16-bit/mono WAV paths (required)
+///   RECORDINGS_BENCH_RUNS             runs per WAV (default 5)
+///   RECORDINGS_BENCH_FINISH_BUDGET_MS finish budget passed to the client (default 10000,
+///                                     deliberately far above production budgets so the
+///                                     observed wait is the true settle latency)
+///   RECORDINGS_BENCH_HOME             home directory the API key is resolved under; the
+///                                     key store reads <home>/.hasna/recordings/config.json
+///                                     (default: the user home)
+///
+/// Results are emitted as BENCH_RESULT lines on stdout, one per run.
+struct RealtimeSettleBenchmark {
+    private static var enabled: Bool {
+        ProcessInfo.processInfo.environment["RECORDINGS_BENCH_REALTIME"] == "1"
+    }
+
+    @Test("realtime settle latency", .enabled(if: RealtimeSettleBenchmark.enabled))
+    @MainActor
+    func settleLatency() async throws {
+        let environment = ProcessInfo.processInfo.environment
+        let wavPaths = (environment["RECORDINGS_BENCH_WAVS"] ?? "")
+            .split(separator: ":").map(String.init)
+        try #require(!wavPaths.isEmpty, "RECORDINGS_BENCH_WAVS is required")
+        let runsPerWav = Int(environment["RECORDINGS_BENCH_RUNS"] ?? "") ?? 5
+        let finishBudget = UInt64(environment["RECORDINGS_BENCH_FINISH_BUDGET_MS"] ?? "") ?? 10_000
+        // OpenAIAPIKeyStore appends .hasna/recordings/config.json to the home it is
+        // given, so this must be the user home itself — not the recordings directory.
+        let keyHome = environment["RECORDINGS_BENCH_HOME"] ?? NSHomeDirectory()
+
+        let apiKey = OpenAIAPIKeyStore.load(homePath: keyHome)
+        try #require(!apiKey.isEmpty, "no API key available from \(keyHome)")
+        let language = OpenAIAPIKeyStore.apiLanguageHint(
+            for: OpenAIAPIKeyStore.loadLanguage(homePath: keyHome)
+        )
+
+        // Client logs must never land in the production Recordings.log.
+        let benchHome = NSTemporaryDirectory() + "recordings-settle-bench-" + UUID().uuidString
+        try FileManager.default.createDirectory(
+            atPath: benchHome, withIntermediateDirectories: true
+        )
+        print("BENCH_HOME \(benchHome)")
+
+        var coldRun = true
+        for wavPath in wavPaths {
+            let pcm = try Self.pcmData(fromWavAtPath: wavPath)
+            let audioSeconds = Double(pcm.count) / 48_000.0
+            for run in 1...runsPerWav {
+                let result = await Self.streamOnce(
+                    pcm: pcm,
+                    apiKey: apiKey,
+                    language: language,
+                    homePath: benchHome,
+                    finishBudgetMilliseconds: finishBudget
+                )
+                let errorField = result.error?
+                    .replacingOccurrences(of: " ", with: "_") ?? ""
+                print(
+                    "BENCH_RESULT wav=\(wavPath) run=\(run) cold=\(coldRun) "
+                        + "audio_seconds=\(String(format: "%.1f", audioSeconds)) "
+                        + "pcm_bytes=\(pcm.count) budget_ms=\(finishBudget) "
+                        + "stream_start_ms=\(result.streamStartMilliseconds) "
+                        + "finish_wait_ms=\(result.finishWaitMilliseconds) "
+                        + "settled=\(result.settled) chars=\(result.textCount) "
+                        + "error=\(errorField)"
+                )
+                coldRun = false
+            }
+        }
+    }
+
+    private struct RunResult {
+        let streamStartMilliseconds: UInt64
+        let finishWaitMilliseconds: UInt64
+        let settled: Bool
+        let textCount: Int
+        let error: String?
+    }
+
+    /// Streams one WAV through a fresh client at capture pace and measures the
+    /// finish/settle wait. A fresh client per run mirrors production: every
+    /// recording builds a new WebSocket session.
+    @MainActor
+    private static func streamOnce(
+        pcm: Data,
+        apiKey: String,
+        language: String,
+        homePath: String,
+        finishBudgetMilliseconds: UInt64
+    ) async -> RunResult {
+        let client = RealtimeTranscriptionClient(apiKey: apiKey, homePath: homePath)
+
+        let startBegan = monotonicMilliseconds()
+        await client.startStreaming(language: language)
+        let streamStart = monotonicMilliseconds() - startBegan
+        guard client.isStreaming else {
+            let text = client.stop()
+            return RunResult(
+                streamStartMilliseconds: streamStart,
+                finishWaitMilliseconds: 0,
+                settled: false,
+                textCount: text.count,
+                error: client.error ?? "failed to start streaming"
+            )
+        }
+
+        // Capture pacing: 4,800 bytes per 100 ms tick (24 kHz * 2 bytes / 10),
+        // periodic commit every 900 ms — the same cadence RecordingEngine uses.
+        let chunkSize = 4_800
+        var offset = 0
+        var lastCommitAt = monotonicMilliseconds()
+        while offset < pcm.count {
+            let end = min(offset + chunkSize, pcm.count)
+            client.sendAudio(pcm.subdata(in: offset..<end))
+            offset = end
+            try? await Task.sleep(for: .milliseconds(100))
+            let now = monotonicMilliseconds()
+            if now - lastCommitAt >= 900 {
+                if await client.commitInput(reason: "periodic") {
+                    lastCommitAt = now
+                }
+            }
+        }
+
+        let finishBegan = monotonicMilliseconds()
+        let finishResult = await client.finish(
+            timeoutMilliseconds: finishBudgetMilliseconds,
+            pipelineID: UUID().uuidString,
+            pipelineStartedUptimeMilliseconds: finishBegan
+        )
+        let finishWait = monotonicMilliseconds() - finishBegan
+        return RunResult(
+            streamStartMilliseconds: streamStart,
+            finishWaitMilliseconds: finishWait,
+            settled: finishResult.settled,
+            textCount: finishResult.text.count,
+            error: finishResult.error
+        )
+    }
+
+    /// Extracts raw PCM from a canonical RIFF/WAVE file, asserting the capture
+    /// pipeline's format (PCM, mono, 24 kHz, 16-bit) so a mispacked fixture cannot
+    /// silently skew the measurement.
+    private static func pcmData(fromWavAtPath path: String) throws -> Data {
+        let data = try Data(contentsOf: URL(fileURLWithPath: path))
+        try #require(data.count > 44, "WAV too small: \(path)")
+        try #require(
+            String(data: data[0..<4], encoding: .ascii) == "RIFF"
+                && String(data: data[8..<12], encoding: .ascii) == "WAVE",
+            "not a RIFF/WAVE file: \(path)"
+        )
+
+        var index = 12
+        var pcm: Data?
+        while index + 8 <= data.count {
+            let chunkID = String(data: data[index..<index + 4], encoding: .ascii) ?? ""
+            let chunkSize = Int(
+                UInt32(data[index + 4]) | UInt32(data[index + 5]) << 8
+                    | UInt32(data[index + 6]) << 16 | UInt32(data[index + 7]) << 24
+            )
+            let body = index + 8
+            guard body + chunkSize <= data.count else { break }
+            if chunkID == "fmt ", chunkSize >= 16 {
+                let format = UInt16(data[body]) | UInt16(data[body + 1]) << 8
+                let channels = UInt16(data[body + 2]) | UInt16(data[body + 3]) << 8
+                let sampleRate = UInt32(data[body + 4]) | UInt32(data[body + 5]) << 8
+                    | UInt32(data[body + 6]) << 16 | UInt32(data[body + 7]) << 24
+                let bits = UInt16(data[body + 14]) | UInt16(data[body + 15]) << 8
+                try #require(
+                    format == 1 && channels == 1 && sampleRate == 24_000 && bits == 16,
+                    "bench WAV must be PCM/mono/24kHz/16-bit: \(path)"
+                )
+            } else if chunkID == "data" {
+                pcm = data.subdata(in: body..<body + chunkSize)
+            }
+            // Chunks are word-aligned: odd sizes carry one padding byte.
+            index = body + chunkSize + (chunkSize % 2)
+        }
+        let payload = try #require(pcm, "no data chunk in \(path)")
+        return payload
+    }
+
+    private static func monotonicMilliseconds() -> UInt64 {
+        UInt64(ProcessInfo.processInfo.systemUptime * 1_000)
+    }
+}

package/src/native/Recordings/RecordingsTests/RealtimeSettleBudgetTests.swift

@@ -0,0 +1,80 @@
+import Foundation
+import Testing
+@testable import RecordingsLib
+
+// MARK: - Realtime settlement budget
+
+struct RealtimeSettleBudgetTests {
+    /// Capture byte rate the budget converts from: 24 kHz, 16-bit, mono.
+    private let bytesPerSecond = 48_000
+
+    @Test("empty and pathological captures get the floor budget")
+    func floorBudget() {
+        #expect(RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: 0) == 1_500)
+        #expect(RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: -1) == 1_500)
+        #expect(RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: 1) == 1_500)
+    }
+
+    @Test("the budget grows with recording length because the fallback cost does")
+    func scalesWithAudioSeconds() {
+        // A ~5 s dictation: the old fixed 700 ms budget was routinely missed by real
+        // settle times (0.6-1.6 s measured); the scaled budget stays comfortably above.
+        #expect(
+            RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: 5 * bytesPerSecond)
+                == 1_500 + 5 * 25
+        )
+        // A one-minute recording is worth a 3 s settlement wait: its fallback pass
+        // costs ~19 s (measured).
+        #expect(
+            RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: 60 * bytesPerSecond)
+                == 3_000
+        )
+    }
+
+    @Test("very long recordings cap at the ceiling instead of stalling the user")
+    func ceilingBudget() {
+        // The 4m07s dictation from the field report: uncapped scaling would ask for
+        // 1_500 + 247*25 = 7_675 ms; the ceiling keeps the wait bounded.
+        #expect(
+            RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: 247 * bytesPerSecond)
+                == 5_000
+        )
+        #expect(
+            RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: Int.max) == 5_000
+        )
+    }
+
+    @Test("partial seconds are rounded down, never up past the ceiling")
+    func partialSeconds() {
+        // 1.9 s of audio counts as 1 whole second of budget scaling.
+        let bytes = Int(Double(bytesPerSecond) * 1.9)
+        #expect(
+            RecordingEngine.realtimeSettleBudgetMilliseconds(pcmByteCount: bytes) == 1_525
+        )
+    }
+}
+
+// MARK: - Realtime outbound send deadlines
+
+struct RealtimeSendDeadlineTests {
+    @Test("the configure send absorbs a cold connection handshake")
+    func configureDeadlineCoversColdHandshake() {
+        // Cold DNS + TCP + TLS + WebSocket upgrade measured 0.77-1.0 s against the
+        // live endpoint from a fresh process; the configure deadline must clear it
+        // with margin or a cold connection poisons the whole session.
+        #expect(RealtimeTranscriptionClient.configureSendTimeoutMilliseconds >= 2_000)
+    }
+
+    @Test("post-configure sends tolerate jitter without outliving the configure budget")
+    func steadyStateDeadlineToleratesJitter() {
+        // One send past the deadline permanently vetoes the fast path, so the
+        // deadline must clear ordinary jitter (a 500 ms value poisoned 3/5 of
+        // two-minute live sessions) while staying under the configure budget —
+        // the bounded outbound queue, not this deadline, is the stall detector.
+        #expect(RealtimeTranscriptionClient.outboundSendTimeoutMilliseconds >= 2_000)
+        #expect(
+            RealtimeTranscriptionClient.outboundSendTimeoutMilliseconds
+                < RealtimeTranscriptionClient.configureSendTimeoutMilliseconds
+        )
+    }
+}

package/src/native/Recordings/RecordingsTests/RealtimeTranscriptionTests.swift

@@ -428,6 +428,21 @@ struct RealtimeTranscriptionTests {
         ) == "final words")
     }
 
+    @Test("A settled transcript survives an unrelated server error")
+    func settledTranscriptSurvivesIncidentalServerError() {
+        let finishResult = RealtimeFinishResult(
+            text: "complete settled transcript",
+            settled: true,
+            error: "server_error: unrelated event"
+        )
+
+        #expect(RecordingEngine.settledRealtimeFallbackTranscript(
+            finishResult: finishResult,
+            pcmByteCount: 96_000,
+            language: "en"
+        ) == "complete settled transcript")
+    }
+
     @Test("Settlement deadline arithmetic saturates at UInt64 bounds")
     @MainActor
     func settlementDeadlineDoesNotOverflow() async {
@@ -560,19 +575,22 @@ struct RealtimeTranscriptionTests {
             postProcessingMode: PostProcessingMode.off.rawValue,
             transcript: "settled realtime text",
             hasSelection: false,
-            intentDetectionEnabled: true
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: "[]"
         ))
         #expect(RecordingEngine.shouldPasteBeforePersistence(
             postProcessingMode: PostProcessingMode.off.rawValue,
             transcript: "rewrite this to be more formal",
             hasSelection: true,
-            intentDetectionEnabled: true
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: "[]"
         ) == false)
         #expect(RecordingEngine.shouldPasteBeforePersistence(
             postProcessingMode: PostProcessingMode.always.rawValue,
             transcript: "settled realtime text",
             hasSelection: false,
-            intentDetectionEnabled: true
+            intentDetectionEnabled: true,
+            enhanceTriggersJSON: "[]"
         ) == false)
         #expect(RecordingEngine.shouldLabelRewriting(
             postProcessingMode: PostProcessingMode.always.rawValue
@@ -666,7 +684,7 @@ struct RealtimeTranscriptionTests {
     @Test("Persistence revision advances only for confirmed saves")
     @MainActor
     func persistenceRevisionTracksConfirmedSaves() {
-        let engine = RecordingEngine()
+        let engine = RecordingEngine(homePath: makeIsolatedTestHome("realtime-tests"))
 
         #expect(engine.persistedRecordingRevision == 0)
         engine.recordPersistenceCompletion(savedText: nil)

package/src/native/Recordings/RecordingsTests/RecordingEngineDeliveryTests.swift

@@ -67,7 +67,7 @@ private func makeEngine(
     accessibilityTrusted: Bool = true,
     pasteRecorder: PasteRecorder? = nil
 ) -> RecordingEngine {
-    let engine = RecordingEngine()
+    let engine = RecordingEngine(homePath: makeIsolatedTestHome("delivery-tests"))
     engine.openAIAPIKeyProvider = { "" }
     engine.microphoneAuthorization = { .denied }
     engine.accessibilityTrustCheck = { accessibilityTrusted }
@@ -295,7 +295,7 @@ struct VoiceShortcutRoutingTests {
     func shortcutBoundaries() async {
         let recorder = PasteRecorder()
         let engine = makeEngine(pasteRecorder: recorder)
-        let shortcuts = VoiceShortcuts()
+        let shortcuts = VoiceShortcuts(homePath: makeIsolatedTestHome("voice-shortcuts"))
         shortcuts.shortcuts = [VoiceShortcut(trigger: "add disclaimer", content: "This is not legal advice.")]
         engine.voiceShortcuts = shortcuts
 
@@ -534,7 +534,7 @@ struct PasteSettlementObservationTests {
         let coordinator = engine.installPasteCoordinatorForTesting(
             schedule: { _, operation in scheduled.append(operation) },
             writeAndVerify: { _ in PasteboardWriteResult(verified: true, ownershipChangeCount: 7) },
-            postPaste: { true }
+            postPaste: { .posted }
         )
         var observations = 0
         let subscription = engine.objectWillChange.sink { _ in observations += 1 }
@@ -562,8 +562,10 @@ struct PasteSettlementObservationTests {
         #expect(engine.canStartRecording)
         let presentation = MenuBarPresentation(
             isRecording: engine.isRecording,
+            isWarmingUpCapture: engine.isWarmingUpCapture,
             canStartRecording: engine.canStartRecording,
-            statusMessage: "Ready"
+            statusMessage: "Ready",
+            blockedReason: nil
         )
         #expect(presentation.iconName == "mic.fill")
         #expect(presentation.primaryActionEnabled, "Start must re-enable from the settlement event alone")
@@ -716,8 +718,10 @@ struct MenuBarEngineContractTests {
         #expect(!engine.canStartRecording)
         let busy = MenuBarPresentation(
             isRecording: engine.isRecording,
+            isWarmingUpCapture: engine.isWarmingUpCapture,
             canStartRecording: engine.canStartRecording,
-            statusMessage: engine.statusMessage
+            statusMessage: engine.statusMessage,
+            blockedReason: nil
         )
         #expect(busy.iconName == "ellipsis.circle")
         #expect(!busy.primaryActionEnabled)
@@ -732,8 +736,10 @@ struct MenuBarEngineContractTests {
         _ = await waitUntil { engine.canStartRecording }
         let idle = MenuBarPresentation(
             isRecording: engine.isRecording,
+            isWarmingUpCapture: engine.isWarmingUpCapture,
             canStartRecording: engine.canStartRecording,
-            statusMessage: "Ready"
+            statusMessage: "Ready",
+            blockedReason: nil
         )
         #expect(idle.iconName == "mic.fill")
         #expect(idle.primaryActionEnabled)

package/src/native/Recordings/RecordingsTests/RecordingEngineHomeIsolationTests.swift

@@ -0,0 +1,67 @@
+import Foundation
+import Testing
+@testable import RecordingsLib
+
+/// Locks the `homePath` seam that keeps a test run out of the operator's real
+/// `~/.hasna/recordings`. `RecordingEngine.init` already creates the audio spool and logs
+/// before it returns, so the seam is only worth anything if it is honoured that early —
+/// these tests assert against artifacts `init` itself produced.
+@MainActor
+struct RecordingEngineHomeIsolationTests {
+    @Test("init writes its log line and audio spool under the injected home, not the real one")
+    func initArtifactsLandUnderInjectedHome() throws {
+        let home = makeIsolatedTestHome("home-isolation")
+
+        let engine = RecordingEngine(homePath: home)
+
+        #expect(engine.home == home)
+        #expect(FileManager.default.fileExists(atPath: "\(home)/.hasna/recordings/audio"))
+
+        // Reading the line back proves the seam reaches NativeAppLog rather than merely
+        // being stored: an unthreaded `home` would leave this file absent here and append
+        // to the real log instead.
+        let logged = try String(
+            contentsOfFile: "\(home)/.hasna/recordings/Recordings.log",
+            encoding: .utf8
+        )
+        #expect(logged.contains("RecordingEngine init"))
+    }
+
+    @Test("every log write the engine makes is addressed to the injected home")
+    func engineLogWritesStayUnderInjectedHome() throws {
+        let first = makeIsolatedTestHome("home-isolation-first")
+        let second = makeIsolatedTestHome("home-isolation-second")
+
+        _ = RecordingEngine(homePath: first)
+        _ = RecordingEngine(homePath: second)
+
+        // Two engines with two homes must not cross-write. A shared or process-global home
+        // would put both init lines in one file and leave the other empty or missing.
+        for home in [first, second] {
+            let logged = try String(
+                contentsOfFile: "\(home)/.hasna/recordings/Recordings.log",
+                encoding: .utf8
+            )
+            #expect(logged.components(separatedBy: "RecordingEngine init").count - 1 == 1)
+        }
+    }
+
+    /// The engine is not the only type that roots itself at the live home. `VoiceShortcuts`
+    /// persists `voice-shortcuts.json` the same way, so a test that adds a shortcut used to
+    /// rewrite the operator's real file. Ported from the same seam work; the structural half of
+    /// this rule is enforced in `src/__tests__/native-test-log-isolation-contract.test.ts`,
+    /// which — unlike this file — can actually run without a Swift toolchain.
+    @Test("voice shortcuts persist under the injected home, not the live one")
+    func voiceShortcutsPersistUnderInjectedHome() throws {
+        let home = makeIsolatedTestHome("home-isolation-shortcuts")
+
+        let shortcuts = VoiceShortcuts(homePath: home)
+        shortcuts.add(trigger: "containment probe", content: "written to a temp home")
+
+        let text = try String(
+            contentsOfFile: "\(home)/.hasna/recordings/voice-shortcuts.json",
+            encoding: .utf8
+        )
+        #expect(text.contains("containment probe"))
+    }
+}

package/src/native/Recordings/RecordingsTests/RecordingStartGateTests.swift

@@ -219,19 +219,28 @@ struct RecordingStartGateTests {
 
     @Test("recording cannot begin while already recording or transcribing")
     func cannotBeginWhenBusy() {
-        #expect(RecordingEngine.canBeginRecording(isRecording: false, isTranscribing: false) == true)
-        #expect(RecordingEngine.canBeginRecording(isRecording: true, isTranscribing: false) == false)
-        #expect(RecordingEngine.canBeginRecording(isRecording: false, isTranscribing: true) == false)
+        #expect(RecordingEngine.canBeginRecording(isRecording: false, isTranscribing: false, isWarmingUpCapture: false) == true)
+        #expect(RecordingEngine.canBeginRecording(isRecording: true, isTranscribing: false, isWarmingUpCapture: false) == false)
+        #expect(RecordingEngine.canBeginRecording(isRecording: false, isTranscribing: true, isWarmingUpCapture: false) == false)
         #expect(RecordingEngine.canBeginRecording(
             isRecording: false,
             isTranscribing: false,
+            isWarmingUpCapture: false,
             isAwaitingMicrophonePermission: true
         ) == false)
         #expect(RecordingEngine.canBeginRecording(
             isRecording: false,
             isTranscribing: false,
+            isWarmingUpCapture: false,
             isDeliveryPending: true
         ) == false)
+        // The warm-up window: `isRecording` is false because no audio has arrived, but the
+        // microphone is open and a second start would open a second recorder on top of it.
+        #expect(RecordingEngine.canBeginRecording(
+            isRecording: false,
+            isTranscribing: false,
+            isWarmingUpCapture: true
+        ) == false)
     }
 
     @Test("recording status is derived from the trigger")