Track per-hop mobile keystroke latency and pacer rate in the existing Axiom window

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalHostTiming.swift

@@ -0,0 +1,142 @@
+/// Mac-side timestamps and pacing state carried on a render-grid frame so the
+/// phone can split keystroke latency into per-hop stages without the Mac
+/// emitting any telemetry of its own.
+///
+/// Attached sparingly to keep wire cost negligible: input stamps only on the
+/// first frame that carries a newly accepted input marker, and a pacer sample
+/// at most about once per second per surface. Every clock value is the Mac's
+/// monotonic uptime in microseconds; the phone never compares these to its own
+/// clock directly (see ``MobileTerminalClockOffsetEstimator``).
+public struct MobileTerminalHostTiming: Codable, Equatable, Sendable {
+    /// When the Mac's input lane first held the input, before the hop to the
+    /// main actor that accepts it.
+    public var inputReceivedMicros: UInt64?
+    /// When the terminal accepted the input.
+    public var inputAcceptedMicros: UInt64?
+    /// When the Mac captured the render-grid frame carrying the echo.
+    public var frameCapturedMicros: UInt64?
+    /// When the encoded frame was handed to the connection queues. Time spent
+    /// in the Mac's send queues after this point is counted as downlink.
+    public var frameDispatchedMicros: UInt64?
+    /// The emission pacer's state for this surface since the previous sample.
+    public var pacer: MobileTerminalPacerSample?
+
+    public init(
+        inputReceivedMicros: UInt64? = nil,
+        inputAcceptedMicros: UInt64? = nil,
+        frameCapturedMicros: UInt64? = nil,
+        frameDispatchedMicros: UInt64? = nil,
+        pacer: MobileTerminalPacerSample? = nil
+    ) {
+        self.inputReceivedMicros = inputReceivedMicros
+        self.inputAcceptedMicros = inputAcceptedMicros
+        self.frameCapturedMicros = frameCapturedMicros
+        self.frameDispatchedMicros = frameDispatchedMicros
+        self.pacer = pacer
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case inputReceivedMicros = "input_received_us"
+        case inputAcceptedMicros = "input_accepted_us"
+        case frameCapturedMicros = "frame_captured_us"
+        case frameDispatchedMicros = "frame_dispatched_us"
+        case pacer
+    }
+
+    /// Whether the input stamps describe one complete, ordered Mac pass.
+    public var hasCompleteInputStamps: Bool {
+        guard let received = inputReceivedMicros,
+              let accepted = inputAcceptedMicros,
+              let captured = frameCapturedMicros,
+              let dispatched = frameDispatchedMicros else { return false }
+        return received <= accepted && accepted <= captured && captured <= dispatched
+    }
+}
+
+/// The emission pacer's state for one surface over one sampling interval.
+public struct MobileTerminalPacerSample: Codable, Equatable, Sendable {
+    /// The pacing period in effect when sampled, in milliseconds.
+    public var periodMillis: Int
+    /// Frames emitted since the previous sample.
+    public var emitted: Int
+    /// Updates coalesced (not captured) since the previous sample.
+    public var coalesced: Int
+    /// Transport shed events that widened the period since the previous sample.
+    public var sheds: Int
+
+    public init(periodMillis: Int, emitted: Int, coalesced: Int, sheds: Int) {
+        self.periodMillis = periodMillis
+        self.emitted = emitted
+        self.coalesced = coalesced
+        self.sheds = sheds
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case periodMillis = "period_ms"
+        case emitted
+        case coalesced
+        case sheds
+    }
+}
+
+/// Splits a keystroke's network time into uplink and downlink across two
+/// unsynchronized monotonic clocks.
+///
+/// One sample is the four NTP timestamps: phone send `t1`, Mac receive `t2`,
+/// Mac dispatch `t3`, phone receive `t4`. The round trip spent on the network
+/// is exact without any clock sync: `(t4 - t1) - (t3 - t2)`. Splitting it
+/// needs the clock offset, which is estimated from the sample with the
+/// smallest network round trip seen so far: queueing inflates delay, so the
+/// quickest exchange is the one whose paths were closest to symmetric. The
+/// split is an estimate; the round trip is not.
+public struct MobileTerminalClockOffsetEstimator: Sendable {
+    /// Estimated (Mac clock - phone clock), in nanoseconds.
+    public private(set) var offsetNanos: Int64?
+    private var bestRoundTripNanos: UInt64?
+
+    public init() {}
+
+    /// Network time for one exchange, in nanoseconds.
+    public struct Split: Equatable, Sendable {
+        public let roundTripNanos: UInt64
+        public let uplinkNanos: UInt64
+        public let downlinkNanos: UInt64
+    }
+
+    /// Records one exchange and returns its network split, or nil when the
+    /// timestamps are inconsistent. Phone times are nanoseconds; Mac times are
+    /// microseconds, as carried on the wire.
+    public mutating func observe(
+        phoneSendNanos t1: UInt64,
+        macReceiveMicros: UInt64,
+        macDispatchMicros: UInt64,
+        phoneReceiveNanos t4: UInt64
+    ) -> Split? {
+        let t2 = macReceiveMicros &* 1_000
+        let t3 = macDispatchMicros &* 1_000
+        guard t4 >= t1, t3 >= t2 else { return nil }
+        let total = t4 - t1
+        let hostTime = t3 - t2
+        guard total >= hostTime else { return nil }
+        let roundTrip = total - hostTime
+        let sampleOffset = (Int64(bitPattern: t2 &- t1) &+ Int64(bitPattern: t3 &- t4)) / 2
+        if bestRoundTripNanos.map({ roundTrip < $0 }) ?? true {
+            bestRoundTripNanos = roundTrip
+            offsetNanos = sampleOffset
+        }
+        let offset = offsetNanos ?? sampleOffset
+        let uplink = Int64(bitPattern: t2 &- t1) &- offset
+        let clampedUplink = UInt64(max(0, min(Int64(roundTrip), uplink)))
+        return Split(
+            roundTripNanos: roundTrip,
+            uplinkNanos: clampedUplink,
+            downlinkNanos: roundTrip - clampedUplink
+        )
+    }
+
+    /// Forget the offset, for a new connection or Mac.
+    public mutating func reset() {
+        offsetNanos = nil
+        bestRoundTripNanos = nil
+    }
+}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalLatencyObserving.swift

@@ -29,6 +29,17 @@ public extension MobileTerminalLatencyObserving {
     func inputStarted(surfaceID: String, byteCount: Int) -> UInt64 {
         inputStarted(surfaceID: surfaceID, byteCount: byteCount, correlate: true)
     }
+
+    /// Mac stage stamps and pacer state carried on a received frame. Called
+    /// before ``outputReceived(surfaceID:appliedInputSequence:byteCount:queueDepth:receivedAtNanos:)``
+    /// for the same frame, while the keystroke's send time is still known.
+    /// Observers that do not split latency per hop ignore it.
+    func hostTimingReceived(
+        surfaceID: String,
+        appliedInputSequence: UInt64?,
+        timing: MobileTerminalHostTiming,
+        receivedAtNanos: UInt64?
+    ) {}
 }
 
 public struct NoopMobileTerminalLatencyObserver: MobileTerminalLatencyObserving {

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGrid.swift

@@ -19,6 +19,9 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
     /// Highest input frame the Mac had received when this frame was captured.
     /// This is a count on the ordered terminal input lane, never terminal text.
     public var appliedInputSequence: UInt64?
+    /// Mac-side stage timestamps and pacer state, attached sparingly (see
+    /// ``MobileTerminalHostTiming``). Nil on most frames and from older Macs.
+    public var hostTiming: MobileTerminalHostTiming?
     /// Stable identifier for one producer lifetime of ``renderRevision``.
     ///
     /// A surface may be recreated with the same public ID after hibernation or
@@ -296,6 +299,7 @@ public struct MobileTerminalRenderGridFrame: Codable, Equatable, Sendable {
             deltaBaseHistoryRows: deltaBaseHistoryRows,
             deltaBaseRenderRevision: deltaBaseRenderRevision
         )
+        hostTiming = try container.decodeIfPresent(MobileTerminalHostTiming.self, forKey: .hostTiming)
     }
 
     public static func fromPlainRows(

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGridFrame+Coding.swift

@@ -29,5 +29,6 @@ extension MobileTerminalRenderGridFrame {
         case deltaBaseHistoryRows = "delta_base_history_rows"
         case deltaBaseRenderRevision = "delta_base_render_revision"
         case rowSpaceRevision = "row_space_revision"
+        case hostTiming = "host_timing"
     }
 }

Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalHostTimingTests.swift

@@ -0,0 +1,106 @@
+import Foundation
+import Testing
+@testable import CMUXMobileCore
+
+private func frame(hostTiming: MobileTerminalHostTiming? = nil) throws -> MobileTerminalRenderGridFrame {
+    var frame = try MobileTerminalRenderGridFrame(
+        surfaceID: "terminal-a",
+        stateSeq: 1,
+        renderEpoch: "epoch-1",
+        renderRevision: 1,
+        columns: 8,
+        rows: 2,
+        full: true,
+        clearedRows: [],
+        rowSpans: [.init(row: 0, column: 0, text: "row")]
+    )
+    frame.hostTiming = hostTiming
+    return frame
+}
+
+@Test func hostTimingRoundTripsOnTheFrame() throws {
+    let timing = MobileTerminalHostTiming(
+        inputReceivedMicros: 1_000,
+        inputAcceptedMicros: 1_200,
+        frameCapturedMicros: 5_000,
+        frameDispatchedMicros: 5_400,
+        pacer: MobileTerminalPacerSample(periodMillis: 90, emitted: 11, coalesced: 16, sheds: 0)
+    )
+    let data = try JSONEncoder().encode(try frame(hostTiming: timing))
+    let decoded = try JSONDecoder().decode(MobileTerminalRenderGridFrame.self, from: data)
+    #expect(decoded.hostTiming == timing)
+    let json = try #require(String(data: data, encoding: .utf8))
+    #expect(json.contains("\"host_timing\""))
+    #expect(json.contains("\"period_ms\":90"))
+}
+
+@Test func framesWithoutTimingDecodeAndOmitTheKey() throws {
+    let data = try JSONEncoder().encode(try frame())
+    let json = try #require(String(data: data, encoding: .utf8))
+    // Most frames carry no timing; the key must not cost bytes on them.
+    #expect(!json.contains("host_timing"))
+    let decoded = try JSONDecoder().decode(MobileTerminalRenderGridFrame.self, from: data)
+    #expect(decoded.hostTiming == nil)
+}
+
+@Test func completeInputStampsRequireOrderedMacPass() {
+    var timing = MobileTerminalHostTiming(
+        inputReceivedMicros: 10, inputAcceptedMicros: 20,
+        frameCapturedMicros: 30, frameDispatchedMicros: 40
+    )
+    #expect(timing.hasCompleteInputStamps)
+    timing.frameCapturedMicros = 15
+    #expect(!timing.hasCompleteInputStamps)
+    timing.frameCapturedMicros = nil
+    #expect(!timing.hasCompleteInputStamps)
+}
+
+@Test func estimatorRoundTripIsExactWithoutClockSync() {
+    var estimator = MobileTerminalClockOffsetEstimator()
+    // Mac clock runs 5s ahead. Uplink 40ms, Mac work 10ms, downlink 60ms.
+    let skew: UInt64 = 5_000_000_000
+    let t1: UInt64 = 1_000_000_000
+    let split = estimator.observe(
+        phoneSendNanos: t1,
+        macReceiveMicros: (t1 + skew + 40_000_000) / 1_000,
+        macDispatchMicros: (t1 + skew + 50_000_000) / 1_000,
+        phoneReceiveNanos: t1 + 110_000_000
+    )
+    #expect(split?.roundTripNanos == 100_000_000)
+    #expect((split?.uplinkNanos ?? 0) + (split?.downlinkNanos ?? 0) == 100_000_000)
+}
+
+@Test func estimatorSplitsUsingTheQuickestExchangesOffset() {
+    var estimator = MobileTerminalClockOffsetEstimator()
+    let skew: UInt64 = 5_000_000_000
+    // Quick, symmetric exchange: 20ms each way. Fixes the offset.
+    var t1: UInt64 = 1_000_000_000
+    _ = estimator.observe(
+        phoneSendNanos: t1,
+        macReceiveMicros: (t1 + skew + 20_000_000) / 1_000,
+        macDispatchMicros: (t1 + skew + 30_000_000) / 1_000,
+        phoneReceiveNanos: t1 + 50_000_000
+    )
+    // A later exchange whose uplink stalled for 900ms (radio wake-up).
+    t1 = 2_000_000_000
+    let stalled = estimator.observe(
+        phoneSendNanos: t1,
+        macReceiveMicros: (t1 + skew + 920_000_000) / 1_000,
+        macDispatchMicros: (t1 + skew + 930_000_000) / 1_000,
+        phoneReceiveNanos: t1 + 950_000_000
+    )
+    // The stall is attributed to the uplink, not smeared across both paths.
+    #expect(stalled?.uplinkNanos == 920_000_000)
+    #expect(stalled?.downlinkNanos == 20_000_000)
+}
+
+@Test func estimatorRejectsInconsistentTimestamps() {
+    var estimator = MobileTerminalClockOffsetEstimator()
+    // Mac work longer than the whole phone-observed exchange is impossible.
+    #expect(estimator.observe(
+        phoneSendNanos: 1_000_000_000,
+        macReceiveMicros: 0,
+        macDispatchMicros: 500_000,
+        phoneReceiveNanos: 1_100_000_000
+    ) == nil)
+}

Packages/iOS/CmuxMobileAnalytics/Sources/CmuxMobileAnalytics/MobileTerminalLatencyReporter.swift

@@ -23,6 +23,20 @@ public final class MobileTerminalLatencyReporter: MobileTerminalLatencyObserving
         var inputToOutput = Array(repeating: 0, count: 17)
         var inputToVisible = Array(repeating: 0, count: 17)
         var render = Array(repeating: 0, count: 17)
+        // Per-hop stages for keystrokes whose echo frame carried Mac stamps.
+        var hostAccept = Array(repeating: 0, count: 17)
+        var hostCapture = Array(repeating: 0, count: 17)
+        var hostDispatch = Array(repeating: 0, count: 17)
+        var networkRoundTrip = Array(repeating: 0, count: 17)
+        var uplink = Array(repeating: 0, count: 17)
+        var downlink = Array(repeating: 0, count: 17)
+        // Mac emission pacer, from samples it attaches at most once a second.
+        var pacerSamples = 0
+        var pacerEmitted = 0
+        var pacerCoalesced = 0
+        var pacerSheds = 0
+        var pacerPeriodMaxMs = 0
+        var pacerPeriod = Array(repeating: 0, count: 17)
         var hasActivity: Bool { inputCount > 0 || failedCount > 0 || outputCount > 0 || presentedCount > 0 || droppedCount > 0 }
     }
 
@@ -37,6 +51,7 @@ public final class MobileTerminalLatencyReporter: MobileTerminalLatencyObserving
         var lastPresentedReceipt: UInt64 = 0
         var lastAnomalyAt: [String: UInt64] = [:]
         var consecutiveSlowFrames = 0
+        var clockOffset = MobileTerminalClockOffsetEstimator()
         init(now: UInt64) { windowStartedAt = now; lastActivityAt = now }
     }
 
@@ -158,6 +173,42 @@ public final class MobileTerminalLatencyReporter: MobileTerminalLatencyObserving
         }
     }
 
+    public func hostTimingReceived(
+        surfaceID: String,
+        appliedInputSequence: UInt64?,
+        timing: MobileTerminalHostTiming,
+        receivedAtNanos: UInt64?
+    ) {
+        guard let surface = state(for: surfaceID) else { return }
+        if let pacer = timing.pacer {
+            surface.window.pacerSamples += 1
+            surface.window.pacerEmitted += max(0, pacer.emitted)
+            surface.window.pacerCoalesced += max(0, pacer.coalesced)
+            surface.window.pacerSheds += max(0, pacer.sheds)
+            surface.window.pacerPeriodMaxMs = max(surface.window.pacerPeriodMaxMs, pacer.periodMillis)
+            Self.record(UInt64(max(0, pacer.periodMillis)) * 1_000_000, in: &surface.window.pacerPeriod)
+        }
+        guard timing.hasCompleteInputStamps,
+              let received = timing.inputReceivedMicros,
+              let accepted = timing.inputAcceptedMicros,
+              let captured = timing.frameCapturedMicros,
+              let dispatched = timing.frameDispatchedMicros else { return }
+        Self.record((accepted - received) * 1_000, in: &surface.window.hostAccept)
+        Self.record((captured - accepted) * 1_000, in: &surface.window.hostCapture)
+        Self.record((dispatched - captured) * 1_000, in: &surface.window.hostDispatch)
+        guard let sequence = appliedInputSequence,
+              let sent = surface.inputStarts[sequence] else { return }
+        guard let split = surface.clockOffset.observe(
+            phoneSendNanos: sent,
+            macReceiveMicros: received,
+            macDispatchMicros: dispatched,
+            phoneReceiveNanos: receivedAtNanos ?? now()
+        ) else { return }
+        Self.record(split.roundTripNanos, in: &surface.window.networkRoundTrip)
+        Self.record(split.uplinkNanos, in: &surface.window.uplink)
+        Self.record(split.downlinkNanos, in: &surface.window.downlink)
+    }
+
     /// The output queue acknowledgment records application, not GPU presentation.
     public func outputApplied(surfaceID: String) {
         states[surfaceID]?.window.appliedCount += 1
@@ -284,9 +335,26 @@ public final class MobileTerminalLatencyReporter: MobileTerminalLatencyObserving
             "dropped_count": .int(w.droppedCount), "output_bytes": .int(w.outputBytes),
             "max_queue_depth": .int(w.maxQueueDepth), "histogram_version": .int(1),
         ]
-        for (name, histogram) in [("input_to_output", w.inputToOutput), ("input_to_visible", w.inputToVisible), ("render", w.render)] {
-            values["\(name)_histogram"] = .string("[" + histogram.map(String.init).joined(separator: ",") + "]")
+        if w.pacerSamples > 0 {
+            values["pacer_sample_count"] = .int(w.pacerSamples)
+            values["pacer_emitted_count"] = .int(w.pacerEmitted)
+            values["pacer_coalesced_count"] = .int(w.pacerCoalesced)
+            values["pacer_shed_count"] = .int(w.pacerSheds)
+            values["pacer_period_max_ms"] = .int(w.pacerPeriodMaxMs)
+        }
+        let stages: [(String, [Int])] = [
+            ("input_to_output", w.inputToOutput), ("input_to_visible", w.inputToVisible), ("render", w.render),
+            ("host_accept", w.hostAccept), ("host_capture", w.hostCapture), ("host_dispatch", w.hostDispatch),
+            ("network_round_trip", w.networkRoundTrip), ("uplink", w.uplink), ("downlink", w.downlink),
+            ("pacer_period", w.pacerPeriod),
+        ]
+        let alwaysEmitted: Set<String> = ["input_to_output", "input_to_visible", "render"]
+        for (name, histogram) in stages {
             let count = histogram.reduce(0, +)
+            // Per-hop stages only appear in windows that measured them, so
+            // idle or legacy-Mac windows add no bytes to the event.
+            if count == 0, !alwaysEmitted.contains(name) { continue }
+            values["\(name)_histogram"] = .string("[" + histogram.map(String.init).joined(separator: ",") + "]")
             for percentile in [50, 95, 99] {
                 var cumulative = 0
                 let rank = max(1, (count * percentile + 99) / 100)