Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more
fix(meeting): Phase 2 - PTS clock latch bug, drift measurement, step detector
Shreeraman A K680b7132e18d
diff --git a/Fluid.xcodeproj/project.pbxproj b/Fluid.xcodeproj/project.pbxprojindex 5e6c82bf..17996bbd 100644--- a/Fluid.xcodeproj/project.pbxproj+++ b/Fluid.xcodeproj/project.pbxproj@@ -39,6 +39,8 @@E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */; };E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000071 /* ClockDomainProbeTests.swift */; };E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */; };+ E5EC000000000000000000A2 /* MeetingTimelineDriftProbeTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */; };+ E5EC00000000000000000092 /* ClockRegressionHelper.swift in Sources */ = {isa = PBXBuildFile; fileRef = E5EC00000000000000000091 /* ClockRegressionHelper.swift */; };A6E2246FA3744C7B3E2DB91C /* MeetingLiveTranscriptionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */; };2952403C87FFDE41C1BC85D5 /* MeetingLiveReplayTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */; };C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */; };@@ -104,6 +106,8 @@E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VoiceProcessingAsrQualityTests.swift; sourceTree = "<group>"; };E5EC00000000000000000071 /* ClockDomainProbeTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ClockDomainProbeTests.swift; sourceTree = "<group>"; };E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingMicrophoneCaptureTests.swift; sourceTree = "<group>"; };+ E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingTimelineDriftProbeTests.swift; sourceTree = "<group>"; };+ E5EC00000000000000000091 /* ClockRegressionHelper.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ClockRegressionHelper.swift; sourceTree = "<group>"; };355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingLiveTranscriptionTests.swift; sourceTree = "<group>"; };7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MeetingLiveReplayTests.swift; sourceTree = "<group>"; };C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AudioEngineRetirementDrainTests.swift; sourceTree = "<group>"; };@@ -217,6 +221,8 @@E5EC00000000000000000061 /* VoiceProcessingAsrQualityTests.swift */,E5EC00000000000000000071 /* ClockDomainProbeTests.swift */,E5EC00000000000000000081 /* MeetingMicrophoneCaptureTests.swift */,+ E5EC000000000000000000A1 /* MeetingTimelineDriftProbeTests.swift */,+ E5EC00000000000000000091 /* ClockRegressionHelper.swift */,355C1248D5386D1F815EB7D7 /* MeetingLiveTranscriptionTests.swift */,7BE63EB94BB280F38F5CB028 /* MeetingLiveReplayTests.swift */,C0DE63600000000000000001 /* AudioEngineRetirementDrainTests.swift */,@@ -415,6 +421,8 @@E5EC00000000000000000062 /* VoiceProcessingAsrQualityTests.swift in Sources */,E5EC00000000000000000072 /* ClockDomainProbeTests.swift in Sources */,E5EC00000000000000000082 /* MeetingMicrophoneCaptureTests.swift in Sources */,+ E5EC000000000000000000A2 /* MeetingTimelineDriftProbeTests.swift in Sources */,+ E5EC00000000000000000092 /* ClockRegressionHelper.swift in Sources */,A6E2246FA3744C7B3E2DB91C /* MeetingLiveTranscriptionTests.swift in Sources */,2952403C87FFDE41C1BC85D5 /* MeetingLiveReplayTests.swift in Sources */,C0DE63600000000000000002 /* AudioEngineRetirementDrainTests.swift in Sources */,diff --git a/MIC_CAPTURE_MIGRATION_PLAN.md b/MIC_CAPTURE_MIGRATION_PLAN.mdindex 4b27e1e8..0ccc8474 100644--- a/MIC_CAPTURE_MIGRATION_PLAN.md+++ b/MIC_CAPTURE_MIGRATION_PLAN.md@@ -162,11 +162,34 @@ design:buffers (device-clock vs mach jitter); widen it — corrections are currently telemetry noise, thoughemitted PTS stayed monotonic and the writer accepted everything.-**Phase 2 — timeline.** *Gate:* drift within Phase 0's bound over 30 minutes. **Absolute offset cannot-be measured with an acoustic click** — AEC removes it, so a failed correlation would mean cancellation-worked. Use a loud chirp and matched-filter the ~33 dB residual; if the residual is unrecoverable,-record that absolute offset is unmeasured, accept ordering-tolerance validation on a real call, and-say so rather than reporting a number.+**Phase 2 — timeline. DONE, 2026-08-15, gate honestly FAILED — with the remedy designed.**++The Phase 1 "corrections on 97% of buffers" finding was a **misdiagnosis**: not HAL jitter but a+latch bug — the correction re-baselined one full accumulation window off (post- vs pre-increment+frame count), so every subsequent stamp re-corrected forever. Reproduced by simulation (drift-only+run predicts first fire at window ~32; field data showed 31 and 34), fixed with one line, and the+first-fire index back-derives the built-in mic's drift as ~6.4 ppm — matching the repo's old+echo-path measurement from an entirely different method.++Cross-path drift gate (8 min, dual capture, guards all zero):+`mic +6.693 ppm (CI ±0.635) | app −0.081 ppm (CI ±0.627) | Δ 6.774, CI_Δ 0.892` → the+budget-derived gate (Δ+CI < 6.9 ppm = ±50 ms over 2 h) **failed by 0.77 ppm**. The mic's sample+clock genuinely runs ~6.7 ppm fast vs mach: 24 ms/hour of skew, 48.8 ms at 2 h — inside budget at+the point estimate, over it with CI, and per-device physics that another machine or a USB mic could+triple.++**Remedy (Phase 3, consumer side):** the clock's correction stream is now a live drift meter+(`cumulativeAbsorbedCorrectionSeconds`, one correction per ~3.2 s, each ≤20.8 µs). The batch+pipeline applies a linear de-drift to mic PTS when mapping onto the shared timeline — one multiply —+holding the budget with ~10× margin for **any** device, which also retires the USB-microphone+concern structurally. Capture-side PTS stays sample-count truth (the invariant: `anchorPTS` is never+moved mid-stream; corrections adjust only the divergence reference and are a no-op on output).++Also built: divergence **step detector** (10 ms threshold; drift moves 0.64 ns/window and cannot+fire it — verified over a simulated 2 h), resync clamp so a backlogged invalid burst can never step+PTS behind emitted audio, timeline reset on `AVAudioEngineConfigurationChange`, and real timebase+values in the probe's track metadata. Absolute cross-path offset remains unmeasured (AEC removes+acoustic stimuli, as reviewed) and is Phase 3's first real-call validation item.**Phase 3 — integrate behind a flag, default off.** *Gate:* a real call whose transcript ordering iscompared turn-by-turn against a human-checked reference. Not a simultaneous old-path capture — twodiff --git a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swiftindex 37360724..642cff78 100644--- a/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift+++ b/Sources/Fluid/Services/Meeting/MeetingMicrophoneCapture.swift@@ -8,9 +8,9 @@ import os// MARK: - PTS clock-/// Anchor-and-count acquisition PTS: per-buffer `hostTime` conversion rounds ±½ tick against exact-/// durations, firing the writer's zero-tolerance backwards check on rounding alone. A valid-/// `hostTime` only corrects the anchor when it diverges by more than one frame.+/// Anchor-and-count acquisition PTS. INVARIANT: emitted PTS is sample-count truth — corrections+/// adjust only the divergence reference, never `anchorPTS`, so they are a no-op on output and+/// double as a drift meter (~one per 3.2 s at the mic's measured ~6.7 ppm).nonisolated struct MeetingMicrophonePTSClock {enum Outcome: Equatable {/// `resynced` is true when this valid stamp follows a post-cap dropped run.@@ -19,6 +19,17 @@ nonisolated struct MeetingMicrophonePTSClock {case droppedPostCap}+ /// Genuine steps only: drift moves 0.64 ns/window, jitter stays in the µs.+ static let divergenceStepThresholdSeconds: Double = 0.010++ private(set) var cumulativeAbsorbedCorrectionSeconds: Double = 0+ private(set) var maxAbsDivergenceSeconds: Double = 0+ private(set) var divergenceStepEventCount = 0+ private(set) var maxDivergenceStepSeconds: Double = 0+ private(set) var resyncClampCount = 0+ private var lastDivergenceSeconds: Double = 0+ private var lastEmittedEnd: CMTime = .invalid+/// Deliberately equal to the writer's 0.5 s gap threshold (`MeetingAudioChunkWriter.swift:181`).static let synthesisCapSeconds: Double = 0.5@@ -30,8 +41,7 @@ nonisolated struct MeetingMicrophonePTSClock {private var anchorHostSeconds: Double?private var anchorPTS: CMTime = .zeroprivate var framesSinceAnchor: Int64 = 0- /// Integer frames, not summed seconds — repeated `Double` addition drifts the cap boundary.- private var synthesizedRunFrames: Int64 = 0+ private var synthesizedRunFrames: Int64 = 0 // integer frames: summed Doubles drift the capprivate var isDroppingInvalidRun = falseinit(sampleRate: Double = Double(Self.timescale), timebase: mach_timebase_info_data_t = Self.machTimebase()) {@@ -60,7 +70,7 @@ nonisolated struct MeetingMicrophonePTSClock {self.framesSinceAnchor = 0}- /// `nil` iff `isHostTimeValid` is false; 0 is a legitimate mach tick, not a sentinel.+ // hostTime nil iff isHostTimeValid false; 0 is a legitimate mach tick, not a sentinelmutating func stamp(hostTime: UInt64?, frameCount: Int) -> Outcome {guard let hostTime else {return self.stampInvalid(frameCount: frameCount)@@ -69,8 +79,7 @@ nonisolated struct MeetingMicrophonePTSClock {}private mutating func stampInvalid(frameCount: Int) -> Outcome {- // No anchor yet: a zero anchor would park the track at epoch 0 vs SCStream's mach stamps.- guard self.anchorHostSeconds != nil else {+ guard self.anchorHostSeconds != nil else { // no anchor: epoch-0 PTS would poison originsreturn .droppedPostCap}if self.isDroppingInvalidRun {@@ -83,6 +92,7 @@ nonisolated struct MeetingMicrophonePTSClock {self.isDroppingInvalidRun = truereturn .droppedPostCap}+ self.noteEmitted(pts: pts, frameCount: frameCount)return .emitted(pts: pts, synthesized: true, anchorCorrected: false, resynced: false)}@@ -93,24 +103,55 @@ nonisolated struct MeetingMicrophonePTSClock {self.synthesizedRunFrames = 0if self.anchorHostSeconds == nil || wasDropping {- self.resetAnchor(hostSeconds: actualSeconds)+ // A backlogged invalid burst can synthesize more timeline than elapsed host time;+ // anchoring behind emitted audio would trip the writer's backwards check.+ var resyncSeconds = actualSeconds+ if self.lastEmittedEnd.isValid, self.lastEmittedEnd.seconds > resyncSeconds {+ resyncSeconds = self.lastEmittedEnd.seconds+ self.resyncClampCount += 1+ }+ self.resetAnchor(hostSeconds: resyncSeconds)+ self.lastDivergenceSeconds = 0let pts = self.currentPTS()self.framesSinceAnchor += Int64(frameCount)+ self.noteEmitted(pts: pts, frameCount: frameCount)return .emitted(pts: pts, synthesized: false, anchorCorrected: wasDropping, resynced: wasDropping)}let expectedSeconds = self.anchorHostSeconds! + Double(self.framesSinceAnchor) / self.sampleRatelet divergence = actualSeconds - expectedSeconds+ self.maxAbsDivergenceSeconds = max(self.maxAbsDivergenceSeconds, abs(divergence))+ let step = abs(divergence - self.lastDivergenceSeconds)+ if step > Self.divergenceStepThresholdSeconds {+ self.divergenceStepEventCount += 1+ self.maxDivergenceStepSeconds = max(self.maxDivergenceStepSeconds, step)+ }+ self.lastDivergenceSeconds = divergencelet pts = self.currentPTS()self.framesSinceAnchor += Int64(frameCount)+ self.noteEmitted(pts: pts, frameCount: frameCount)var corrected = falseif abs(divergence) > 1.0 / self.sampleRate {- self.anchorHostSeconds = actualSeconds - Double(self.framesSinceAnchor) / self.sampleRate+ // += divergence; using the post-increment count latches one window off (97% bug).+ self.anchorHostSeconds! += divergence+ self.cumulativeAbsorbedCorrectionSeconds += divergence+ self.lastDivergenceSeconds = 0corrected = true}return .emitted(pts: pts, synthesized: false, anchorCorrected: corrected, resynced: false)}++ private mutating func noteEmitted(pts: CMTime, frameCount: Int) {+ self.lastEmittedEnd = CMTimeAdd(pts, CMTime(value: Int64(frameCount), timescale: Self.timescale))+ }++ mutating func requestTimelineReset() {+ self.anchorHostSeconds = nil+ self.isDroppingInvalidRun = false+ self.synthesizedRunFrames = 0+ self.lastDivergenceSeconds = 0+ }}// MARK: - CMSampleBuffer synthesis (free function, no AVAudioEngine dependency)@@ -302,6 +343,11 @@ final class MeetingMicrophoneCaptureStats: @unchecked Sendable {var defaultInputChangeEvents = 0var tapCallbackMaxDurationSeconds: Double = 0var tapCallbackP99DurationSeconds: Double = 0+ var cumulativeAbsorbedCorrectionSeconds: Double = 0+ var maxAbsDivergenceSeconds: Double = 0+ var divergenceStepEventCount = 0+ var maxDivergenceStepSeconds: Double = 0+ var resyncClampCount = 0/// The Phase 1 gate's headline number: ≥99% valid hostTime over the run.var validHostTimeFraction: Double {@@ -396,6 +442,7 @@ private final class MeetingMicrophoneTapState: @unchecked Sendable {let start = DispatchTime.now()defer { self.statsBox.recordCallbackDuration(Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000) }+ self.consumePendingResetIfNeeded()self.checkSequenceContinuity(time: time, frameCount: Int(buffer.frameLength))let converted = self.convertToMono(buffer)@@ -442,15 +489,44 @@ private final class MeetingMicrophoneTapState: @unchecked Sendable {return}+ let clock = self.clockself.statsBox.mutate { stats instats.buffersEmitted += 1if synthesized { stats.synthesizedCount += 1 } else { stats.validHostTimeCount += 1 }if anchorCorrected { stats.anchorCorrectionCount += 1 }if resynced { stats.resyncCount += 1 }+ stats.cumulativeAbsorbedCorrectionSeconds = clock.cumulativeAbsorbedCorrectionSeconds+ stats.maxAbsDivergenceSeconds = clock.maxAbsDivergenceSeconds+ stats.divergenceStepEventCount = clock.divergenceStepEventCount+ stats.maxDivergenceStepSeconds = clock.maxDivergenceStepSeconds+ stats.resyncClampCount = clock.resyncClampCount}self.onSample(sampleBuffer)}+ /// Set off the tap thread; consumed at the next callback so the clock re-anchors.+ func requestTimelineReset() {+ self.pendingTimelineReset.withLock { $0 = true }+ }++ private let pendingTimelineReset = OSAllocatedUnfairLock(initialState: false)++ private func consumePendingResetIfNeeded() {+ let pending = self.pendingTimelineReset.withLock { flag -> Bool in+ defer { flag = false }+ return flag+ }+ if pending {+ self.clock.requestTimelineReset()+ self.accumulated.removeAll(keepingCapacity: true)+ self.windowHostTime = nil+ self.windowHostTimeValid = false+ self.lastExpectedSampleTime = nil+ self.converter = nil+ self.converterSourceFormat = nil+ }+ }+/// Resample first, then downmix explicitly — converter channel mapping may drop, not mix.private func convertToMono(_ buffer: AVAudioPCMBuffer) -> [Float]? {let sourceFormat = buffer.format@@ -537,6 +613,7 @@ actor MeetingMicrophoneCapture {private let generationBox = MeetingMicrophoneGenerationBox()private var engine: AVAudioEngine?+ private var tapState: MeetingMicrophoneTapState?private var isRunning = falseprivate var settled: MeetingMicrophoneSettledConfig?private var configObserver: NSObjectProtocol?@@ -584,14 +661,14 @@ actor MeetingMicrophoneCapture {// TODO(probe): bind order is a Phase-1 measurement; this hard-codes one attempt.let bindStatus = Self.bindInputDevice(audioUnit, to: requestedDeviceID)- // The tap must exist before start(): the active graph is built at start, and a tap added to- // a node with no connections afterwards sits on an inactive node — measured as 10 minutes of- // zero callbacks while everything else reported healthy.+ // Tap before start(): added afterwards it sits on an inactive node — measured as+ // 10 minutes of zero callbacks with healthy telemetry.let preStartFormat = input.outputFormat(forBus: 0)guard preStartFormat.sampleRate > 0, preStartFormat.channelCount > 0 else {return self.fail(microphone: microphone, reason: "Input format invalid before start (\(preStartFormat)).")}let tapState = MeetingMicrophoneTapState(statsBox: self.statsBox, canonicalFormat: Self.canonicalFormat, onSample: onSample)+ self.tapState = tapStatelet generationBox = self.generationBoxinput.installTap(onBus: 0, bufferSize: 4_800, format: preStartFormat) { buffer, time inguard generationBox.isCurrent(currentGeneration) else { return }@@ -660,6 +737,7 @@ actor MeetingMicrophoneCapture {engine.stop()}self.engine = nil+ self.tapState = nilself.tearDownEventObservers()}@@ -711,8 +789,9 @@ actor MeetingMicrophoneCapture {// delivery is load-bearing (avoids a deadlock against the engine's own serial queue).self.configObserver = NotificationCenter.default.addObserver(forName: .AVAudioEngineConfigurationChange, object: engine, queue: nil- ) { _ in+ ) { [weak tapState = self.tapState] _ instatsBox.mutate { $0.configurationChangeEvents += 1 }+ tapState?.requestTimelineReset()onEvent(.configurationChanged)}@@ -774,9 +853,8 @@ actor MeetingMicrophoneCapture {}}- /// On an I/O unit element 1 is the input side and element 0 the render side. Element 0 here- /// would set — and read back — the OUTPUT device: measured as "bound 85 (AirPods output) does- /// not match requested 78 (built-in mic)" while VPIO's echo reference silently stayed put.+ /// Element 1 is the input side; element 0 would set/read the OUTPUT device (measured: read-back+ /// returned the AirPods output against a requested built-in mic).private static let inputElement: AudioUnitElement = 1private static let outputElement: AudioUnitElement = 0@@ -813,8 +891,7 @@ actor MeetingMicrophoneCapture {// MARK: - Opt-in hardware probe-/// Real-hardware Phase 1 gate (plan §9), foreground only. `FLUIDVOICE_MIC_PHASE1=<minutes>`;-/// `FLUIDVOICE_MIC_PHASE1_DEVICE` selects the Bluetooth leg.+/// Real-hardware Phase 1 gate (plan §9), foreground only; env FLUIDVOICE_MIC_PHASE1[_DEVICE].enum MeetingMicrophonePhase1Probe {struct Result: Sendable {var minutes: Double@@ -851,8 +928,12 @@ enum MeetingMicrophonePhase1Probe {format: nil,timebase: MeetingTimebaseMetadata(startedHostTime: mach_absolute_time(),- machTimebaseNumerator: 0,- machTimebaseDenominator: 0,+ machTimebaseNumerator: {+ var info = mach_timebase_info_data_t(); mach_timebase_info(&info); return info.numer+ }(),+ machTimebaseDenominator: {+ var info = mach_timebase_info_data_t(); mach_timebase_info(&info); return info.denom+ }(),firstPresentationTime: nil),health: .waiting,diff --git a/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swiftindex f1cd5241..0f87964e 100644--- a/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift+++ b/Tests/FluidDictationIntegrationTests/ClockDomainProbeTests.swift@@ -74,61 +74,6 @@ final class ClockDomainProbeTests: XCTestCase {}}-/// Records (mach seconds, SCStream PTS seconds) pairs and fits PTS = a + b·mach by least squares.-private actor ClockPairRecorder {- struct Fit {- let count: Int- let slopePPM: Double- let slopeCI95PPM: Double- let residualStdMs: Double- let ptsSpanSeconds: Double- }-- private var machTimes: [Double] = []- private var ptsTimes: [Double] = []-- func record(mach: Double, pts: Double) {- self.machTimes.append(mach)- self.ptsTimes.append(pts)- }-- func regression() -> Fit? {- let n = self.machTimes.count- guard n > 10 else { return nil }- let x0 = self.machTimes[0]- let y0 = self.ptsTimes[0]- let xs = self.machTimes.map { $0 - x0 }- let ys = self.ptsTimes.map { $0 - y0 }- let sumX = xs.reduce(0, +)- let sumY = ys.reduce(0, +)- let meanX = sumX / Double(n)- let meanY = sumY / Double(n)- var sxx = 0.0- var sxy = 0.0- for i in 0..<n {- let dx = xs[i] - meanX- sxx += dx * dx- sxy += dx * (ys[i] - meanY)- }- guard sxx > 0 else { return nil }- let slope = sxy / sxx- var sse = 0.0- let intercept = meanY - slope * meanX- for i in 0..<n {- let r = ys[i] - (intercept + slope * xs[i])- sse += r * r- }- let residualVariance = sse / Double(max(1, n - 2))- let slopeStdErr = (residualVariance / sxx).squareRoot()- return Fit(- count: n,- slopePPM: (slope - 1) * 1_000_000,- slopeCI95PPM: 1.96 * slopeStdErr * 1_000_000,- residualStdMs: residualVariance.squareRoot() * 1_000,- ptsSpanSeconds: ys.last ?? 0- )- }-}private final class ClockProbeOutput: NSObject, SCStreamOutput {private let recorder: ClockPairRecorderdiff --git a/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swift b/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swiftnew file mode 100644index 00000000..4d98728d--- /dev/null+++ b/Tests/FluidDictationIntegrationTests/ClockRegressionHelper.swift@@ -0,0 +1,75 @@+import Foundation++/// Least-squares fit of a (mach seconds, PTS seconds) series, shared by the Phase 0 clock-domain+/// probe and the Phase 2 cross-path drift probe. Regression, never per-sample deltas: arrival+/// jitter perturbs points, not a long-run slope.+final actor ClockPairRecorder {+ struct Fit {+ let count: Int+ let slopePPM: Double+ let slopeCI95PPM: Double+ let residualStdMs: Double+ let ptsSpanSeconds: Double+ }++ private var machTimes: [Double] = []+ private var ptsTimes: [Double] = []++ func record(mach: Double, pts: Double) {+ self.machTimes.append(mach)+ self.ptsTimes.append(pts)+ }++ func count() -> Int { self.machTimes.count }++ func regression() -> Fit? {+ Self.fit(machTimes: self.machTimes, ptsTimes: self.ptsTimes)+ }++ /// Fits each half separately: a warm-up drift transient shows as disagreeing halves even when+ /// the whole-run CI looks tight.+ func halfSplitSlopesPPM() -> (first: Double, second: Double)? {+ let n = self.machTimes.count+ guard n > 200 else { return nil }+ let mid = n / 2+ guard let a = Self.fit(machTimes: Array(self.machTimes[..<mid]), ptsTimes: Array(self.ptsTimes[..<mid])),+ let b = Self.fit(machTimes: Array(self.machTimes[mid...]), ptsTimes: Array(self.ptsTimes[mid...]))+ else { return nil }+ return (a.slopePPM, b.slopePPM)+ }++ static func fit(machTimes: [Double], ptsTimes: [Double]) -> Fit? {+ let n = machTimes.count+ guard n > 10 else { return nil }+ let x0 = machTimes[0]+ let y0 = ptsTimes[0]+ let xs = machTimes.map { $0 - x0 }+ let ys = ptsTimes.map { $0 - y0 }+ let meanX = xs.reduce(0, +) / Double(n)+ let meanY = ys.reduce(0, +) / Double(n)+ var sxx = 0.0+ var sxy = 0.0+ for i in 0..<n {+ let dx = xs[i] - meanX+ sxx += dx * dx+ sxy += dx * (ys[i] - meanY)+ }+ guard sxx > 0 else { return nil }+ let slope = sxy / sxx+ let intercept = meanY - slope * meanX+ var sse = 0.0+ for i in 0..<n {+ let r = ys[i] - (intercept + slope * xs[i])+ sse += r * r+ }+ let residualVariance = sse / Double(max(1, n - 2))+ let slopeStdErr = (residualVariance / sxx).squareRoot()+ return Fit(+ count: n,+ slopePPM: (slope - 1) * 1_000_000,+ slopeCI95PPM: 1.96 * slopeStdErr * 1_000_000,+ residualStdMs: residualVariance.squareRoot() * 1_000,+ ptsSpanSeconds: ys.last ?? 0+ )+ }+}diff --git a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swiftindex 0bbd505a..dcd3f21a 100644--- a/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift+++ b/Tests/FluidDictationIntegrationTests/MeetingMicrophoneCaptureTests.swift@@ -402,3 +402,89 @@ final class MeetingMicrophoneCaptureTests: XCTestCase {XCTAssertEqual(track.chunks.first?.discontinuities.map(\.kind), [.sourceLost])}}++// MARK: - Phase 2: correction latch, step detector, resync clamp++extension MeetingMicrophoneCaptureTests {+ /// The Phase 1 field data (corrections on ~97% of buffers) was a latch: the correction+ /// re-baselined one full window off, so every subsequent stamp re-corrected forever.+ func testCorrectionDoesNotLatchAcrossSubsequentStamps() {+ var clock = self.makeClock()+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)+ // Force one genuine correction with a 5ms excursion…+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0.105), frameCount: 4_800)+ // …then five contiguous jitter-free stamps on the shifted timeline: zero further corrections.+ for i in 2...6 {+ let outcome = clock.stamp(hostTime: self.hostTime(seconds: 0.005 + Double(i) * 0.1), frameCount: 4_800)+ guard case let .emitted(_, _, corrected, _) = outcome else { return XCTFail("expected emission") }+ XCTAssertFalse(corrected, "stamp \(i) re-corrected: the latch is back")+ }+ }++ /// A correction is a no-op on output: the next buffer's PTS continues exactly from the+ /// previous end.+ func testCorrectionLeavesEmittedPTSContinuous() {+ var clock = self.makeClock()+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)+ guard case let .emitted(before, _, corrected1, _) = clock.stamp(hostTime: self.hostTime(seconds: 0.108), frameCount: 4_800) else {+ return XCTFail("expected emission")+ }+ XCTAssertTrue(corrected1)+ guard case let .emitted(after, _, _, _) = clock.stamp(hostTime: self.hostTime(seconds: 0.208), frameCount: 4_800) else {+ return XCTFail("expected emission")+ }+ XCTAssertEqual(after.seconds - before.seconds, 0.1, accuracy: 1.0 / 48_000)+ }++ /// Drift must never fire the step detector: 6.4 ppm over a simulated two hours.+ func testSlowDriftNeverFiresTheStepDetector() {+ var clock = self.makeClock()+ let windows = 72_000 // 2h of 100ms windows+ for i in 0..<windows {+ let actual = Double(i) * 0.1 * (1 + 6.4e-6)+ _ = clock.stamp(hostTime: self.hostTime(seconds: actual), frameCount: 4_800)+ }+ XCTAssertEqual(clock.divergenceStepEventCount, 0)+ XCTAssertGreaterThan(clock.cumulativeAbsorbedCorrectionSeconds, 0, "drift shows up as absorbed corrections")+ }++ func testSingleJumpFiresExactlyOneStepEvent() {+ var clock = self.makeClock()+ for i in 0..<10 {+ _ = clock.stamp(hostTime: self.hostTime(seconds: Double(i) * 0.1), frameCount: 4_800)+ }+ _ = clock.stamp(hostTime: self.hostTime(seconds: 1.0 + 0.050), frameCount: 4_800) // 50ms step+ for i in 11..<20 {+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0.050 + Double(i) * 0.1), frameCount: 4_800)+ }+ XCTAssertEqual(clock.divergenceStepEventCount, 1)+ XCTAssertEqual(clock.maxDivergenceStepSeconds, 0.050, accuracy: 0.001)+ }++ /// A backlogged invalid burst can synthesize more timeline than elapsed host time; the resync+ /// anchor clamps forward so PTS never steps behind emitted audio.+ func testResyncNeverStepsBehindEmittedAudio() {+ var clock = self.makeClock()+ _ = clock.stamp(hostTime: self.hostTime(seconds: 0), frameCount: 4_800)+ // 500ms of synthesized emission (cap-inclusive), delivered as a burst…+ for _ in 0..<5 { _ = clock.stamp(hostTime: nil, frameCount: 4_800) }+ _ = clock.stamp(hostTime: nil, frameCount: 4_800) // over cap → dropping+ // …then a valid stamp whose host time is EARLIER than the emitted end (0.6s emitted, 0.3s wall).+ guard case let .emitted(pts, _, _, resynced) = clock.stamp(hostTime: self.hostTime(seconds: 0.3), frameCount: 4_800) else {+ return XCTFail("expected resync emission")+ }+ XCTAssertTrue(resynced)+ XCTAssertGreaterThanOrEqual(pts.seconds, 0.6 - 1.0 / 48_000, "resync anchored behind already-emitted audio")+ XCTAssertEqual(clock.resyncClampCount, 1)+ }++ func testTimelineResetReanchorsOnNextValidStamp() {+ var clock = self.makeClock()+ _ = clock.stamp(hostTime: self.hostTime(seconds: 5), frameCount: 4_800)+ clock.requestTimelineReset()+ guard case let .emitted(pts, _, _, _) = clock.stamp(hostTime: self.hostTime(seconds: 9), frameCount: 4_800) else {+ return XCTFail("expected emission after reset")+ }+ XCTAssertEqual(pts.seconds, 9.0, accuracy: 1.0 / 48_000)+ }+}diff --git a/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swift b/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swiftnew file mode 100644index 00000000..911526b8--- /dev/null+++ b/Tests/FluidDictationIntegrationTests/MeetingTimelineDriftProbeTests.swift@@ -0,0 +1,170 @@+@testable import FluidVoice_Debug+import AudioToolbox+import AVFoundation+import CoreMedia+import Foundation+import ScreenCaptureKit+import XCTest++/// Phase 2 gate: do the two capture paths' clocks stay in step? Runs `MeetingMicrophoneCapture`+/// (VPIO, built-in mic) and an SCStream audio capture simultaneously, regressing each path's+/// emitted PTS against mach wall time.+///+/// Gate: |slope_mic − slope_app| + CI_Δ < 6.9 ppm — derived from the ±50 ms ordering budget over a+/// 2-hour meeting (50 ms / 7200 s), NOT from Phase 0's 20 ppm domain check, which answered a+/// different question. Absolute cross-path offset is not measurable acoustically (AEC removes the+/// stimulus at ~33 dB); the deterministic latency components are printed instead as the Phase 3+/// estimate. Preconditions: foreground session, unlocked display, speakers (not Bluetooth — VPIO+/// delivers nothing on a BT render route), VPIO ducking audible during the run.+///+/// Run with FLUIDVOICE_DRIFT_PROBE=<minutes>.+final class MeetingTimelineDriftProbeTests: XCTestCase {+ private static let gatePPM = 6.9+ private static let ciBudgetPPM = 1.4 // 20% of the gate; wider means "extend the run", not "pass"++ func testCrossPathClockDrift() async throws {+ guard let minutesString = ProcessInfo.processInfo.environment["FLUIDVOICE_DRIFT_PROBE"],+ let minutes = Double(minutesString), minutes > 0+ else { throw XCTSkip("FLUIDVOICE_DRIFT_PROBE not set") }++ let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)+ guard let display = content.displays.first else { throw XCTSkip("no display") }+ let filter = SCContentFilter(display: display, excludingApplications: [], exceptingWindows: [])+ let configuration = SCStreamConfiguration()+ configuration.width = 2+ configuration.height = 2+ configuration.minimumFrameInterval = CMTime(value: 1, timescale: 1)+ configuration.queueDepth = 3+ configuration.showsCursor = false+ configuration.capturesAudio = true+ configuration.sampleRate = 48_000+ configuration.channelCount = 2+ configuration.excludesCurrentProcessAudio = true++ let appRecorder = ClockPairRecorder()+ let appOutput = DriftStreamOutput(recorder: appRecorder)+ let stream = SCStream(filter: filter, configuration: configuration, delegate: nil)+ try stream.addStreamOutput(appOutput, type: .audio, sampleHandlerQueue: DispatchQueue(label: "drift.app"))+ try await stream.startCapture()+ defer { Task { try? await stream.stopCapture() } }++ let temp = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)+ try FileManager.default.createDirectory(at: temp, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: temp) }++ let microphone = try MeetingCaptureSourceCatalog.defaultMicrophone(preferredCoreAudioUID: "BuiltInMicrophoneDevice")+ var writerDiscontinuities = 0+ let track = MeetingAudioTrack(+ id: UUID(), kind: .microphone,+ sourceIdentifier: microphone.captureDeviceID, sourceDisplayName: microphone.displayName,+ format: nil,+ timebase: MeetingTimebaseMetadata(+ startedHostTime: mach_absolute_time(),+ machTimebaseNumerator: Self.timebase.numer,+ machTimebaseDenominator: Self.timebase.denom,+ firstPresentationTime: nil+ ),+ health: .waiting, chunks: []+ )+ let writer = try MeetingAudioChunkWriter(track: track, sessionDirectory: temp, chunkDuration: 60) { _ in }++ let micRecorder = ClockPairRecorder()+ let capture = MeetingMicrophoneCapture()+ let outcome = try await capture.start(microphone: microphone) { sampleBuffer in+ // Mach sampled synchronously on the tap thread, before the writer hop.+ let mach = Double(mach_absolute_time()) * Self.timebaseSeconds+ let pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer)+ if pts.isValid {+ Task { await micRecorder.record(mach: mach, pts: pts.seconds) }+ }+ writer.enqueue(sampleBuffer)+ }+ guard case .boundVerified = outcome else {+ throw XCTSkip("mic not bindable in this environment: \(outcome)")+ }+ Self.printLatencyEstimate(capture: await capture.settledConfiguration())++ let seconds = minutes * 60+ var elapsed = 0.0+ while elapsed < seconds {+ let step = min(60.0, seconds - elapsed)+ try await Task.sleep(nanoseconds: UInt64(step * 1_000_000_000))+ elapsed += step+ if elapsed >= 30, await micRecorder.count() == 0 {+ XCTFail("no mic buffers after 30s — Bluetooth render route or dead capture")+ await capture.stop()+ return+ }+ let mic = await micRecorder.regression()+ let app = await appRecorder.regression()+ print(String(+ format: "[drift] t=%4.0fs mic n=%5d slope=%+7.3f ppm | app n=%6d slope=%+7.3f ppm",+ elapsed, mic?.count ?? 0, mic?.slopePPM ?? .nan, app?.count ?? 0, app?.slopePPM ?? .nan+ ))+ }++ await capture.stop()+ let finishedTrack = await writer.stop()+ writerDiscontinuities = finishedTrack.chunks.reduce(0) { $0 + $1.discontinuities.count }+ let stats = await capture.statistics()++ guard let mic = await micRecorder.regression(), let app = await appRecorder.regression() else {+ return XCTFail("insufficient samples for regression")+ }+ let delta = abs(mic.slopePPM - app.slopePPM)+ let ciDelta = (mic.slopeCI95PPM * mic.slopeCI95PPM + app.slopeCI95PPM * app.slopeCI95PPM).squareRoot()+ let micHalves = await micRecorder.halfSplitSlopesPPM()++ print(String(format: "\n[drift] mic slope=%+.3f ppm (CI ±%.3f) residual=%.2f ms n=%d", mic.slopePPM, mic.slopeCI95PPM, mic.residualStdMs, mic.count))+ print(String(format: "[drift] app slope=%+.3f ppm (CI ±%.3f) residual=%.2f ms n=%d", app.slopePPM, app.slopeCI95PPM, app.residualStdMs, app.count))+ print(String(format: "[drift] Δ=%.3f ppm CI_Δ=%.3f → projected skew %.1f ms/hour", delta, ciDelta, (delta + ciDelta) * 3.6))+ if let halves = micHalves {+ print(String(format: "[drift] mic half-split: %+.3f / %+.3f ppm (Δ=%.3f)", halves.first, halves.second, abs(halves.first - halves.second)))+ }+ print("[drift] guards: seqViolations=\(stats.sequenceContinuityViolations) convFail=\(stats.conversionFailures) droppedPostCap=\(stats.droppedPostCapCount) resyncs=\(stats.resyncCount) writerDisc=\(writerDiscontinuities) configChanges=\(stats.configurationChangeEvents) corrections=\(stats.anchorCorrectionCount) absorbed=\(String(format: "%.3f", stats.cumulativeAbsorbedCorrectionSeconds * 1_000))ms stepEvents=\(stats.divergenceStepEventCount)")+ print("[drift] NOTE: absolute cross-path offset is unmeasured here (AEC removes acoustic stimuli); Phase 3 validates it on a real call.")++ if stats.configurationChangeEvents > 0 {+ throw XCTSkip("configuration changed mid-run — probe artifact, re-run")+ }+ XCTAssertEqual(stats.sequenceContinuityViolations, 0)+ XCTAssertEqual(stats.conversionFailures, 0)+ XCTAssertEqual(stats.droppedPostCapCount, 0)+ XCTAssertEqual(stats.resyncCount, 0)+ XCTAssertEqual(writerDiscontinuities, 0)+ XCTAssertLessThanOrEqual(ciDelta, Self.ciBudgetPPM, "CI too wide — extend the run rather than trusting the point estimate")+ XCTAssertLessThan(delta + ciDelta, Self.gatePPM, "cross-path drift violates the ±50ms/2h ordering budget")+ }++ private static let timebase: mach_timebase_info_data_t = {+ var info = mach_timebase_info_data_t()+ mach_timebase_info(&info)+ return info+ }()+ private static let timebaseSeconds = Double(timebase.numer) / Double(timebase.denom) / 1_000_000_000++ /// The deterministic latency components — the Phase 3 absolute-offset estimate.+ private static func printLatencyEstimate(capture settled: MeetingMicrophoneSettledConfig?) {+ guard let settled else { return }+ print("[drift] settled: input=\(settled.settledInputDeviceUID ?? "?") output=\(settled.settledOutputDeviceUID ?? "?") source=\(settled.sourceSampleRate)Hz/\(settled.sourceChannelCount)ch")+ }+}++private final class DriftStreamOutput: NSObject, SCStreamOutput {+ private let recorder: ClockPairRecorder+ private static let timebaseSeconds: Double = {+ var info = mach_timebase_info_data_t()+ mach_timebase_info(&info)+ return Double(info.numer) / Double(info.denom) / 1_000_000_000+ }()++ init(recorder: ClockPairRecorder) { self.recorder = recorder }++ func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {+ guard type == .audio else { return }+ let pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer)+ guard pts.isValid else { return }+ let mach = Double(mach_absolute_time()) * Self.timebaseSeconds+ Task { [recorder] in await recorder.record(mach: mach, pts: pts.seconds) }+ }+}