feat(polish): add question guard, ABE routing, and flow trace

Harden polish so question drafts stay questions, add local density routing with style-specific degrade, expand fun style packs, and add end-to-end FlowTrace logging plus offline guard eval scripts.
2026-07-29 16:17:16 +08:00
parent d656bac8c3
commit 65fe3a81b4
19 changed files with 1443 additions and 71 deletions
@@ -0,0 +1,99 @@
+// FlowTrace.swift
+// OSGKeyboard · Shared
+//
+// One greppable trace channel for the whole voice path:
+//
+//   capture → downsample → utterance gate → chunker → ASR → polish → keyboard
+//
+// Every line is `[trace] stage=<area>.<step> key=value …`, so a single
+// Console.app filter (subsystem `com.osgkeyboard.ios`, message contains
+// `[trace]`) replays one utterance end to end. The `stage=` tag keeps the
+// stages sortable, which matters because the pipeline spans two processes
+// (main app captures and recognises, keyboard extension inserts).
+//
+// Transcript payloads are logged in the clear only in DEBUG builds. Release
+// builds mark them `.private` so recognised speech never lands in a sysdiagnose
+// the user shares with a third party.
+
+import Foundation
+import os
+
+public enum FlowTrace {
+
+    // MARK: - Stage channels
+
+    /// Mic capture and audio plumbing (engine, converter, gate, drain).
+    public static func capture(_ step: String, _ detail: String = "") {
+        OSGLog.flow.info("[trace] stage=capture.\(step, privacy: .public) \(detail, privacy: .public)")
+    }
+
+    /// Chunking and transcript stitching between capture and the ASR engine.
+    public static func pipeline(_ step: String, _ detail: String = "") {
+        OSGLog.flow.info("[trace] stage=pipeline.\(step, privacy: .public) \(detail, privacy: .public)")
+    }
+
+    /// Recognition engine boundary (local SpeechAnalyzer or cloud provider).
+    public static func asr(_ step: String, _ detail: String = "") {
+        OSGLog.asr.info("[trace] stage=asr.\(step, privacy: .public) \(detail, privacy: .public)")
+    }
+
+    /// LLM polish / translation stage.
+    public static func polish(_ step: String, _ detail: String = "") {
+        OSGLog.flow.info("[trace] stage=polish.\(step, privacy: .public) \(detail, privacy: .public)")
+    }
+
+    /// Keyboard extension side: result delivery and text insertion.
+    public static func keyboard(_ step: String, _ detail: String = "") {
+        OSGLog.keyboardExt.info("[trace] stage=keyboard.\(step, privacy: .public) \(detail, privacy: .public)")
+    }
+
+    /// Paths that used to fail silently (dropped audio, empty transcripts).
+    /// Logged at `warning` so they stand out without changing the filter.
+    public static func warn(_ step: String, _ detail: String = "") {
+        OSGLog.flow.warning("[trace] stage=\(step, privacy: .public) \(detail, privacy: .public) OUTCOME=SUSPECT")
+    }
+
+    // MARK: - Transcript payloads
+
+    /// Logs recognised / polished text plus its length.
+    ///
+    /// `step` names the point in the path (`asr.chunk`, `asr.final`,
+    /// `polish.input`, `polish.output`, `keyboard.insert`), so a diff between
+    /// two adjacent `text.*` lines shows exactly which stage changed the text.
+    public static func transcript(_ step: String, _ text: String, _ detail: String = "") {
+        let length = text.count
+        let empty = text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        #if DEBUG
+        OSGLog.asr.info(
+            "[trace] stage=text.\(step, privacy: .public) len=\(length, privacy: .public) empty=\(empty, privacy: .public) \(detail, privacy: .public) text=\(text, privacy: .public)"
+        )
+        #else
+        OSGLog.asr.info(
+            "[trace] stage=text.\(step, privacy: .public) len=\(length, privacy: .public) empty=\(empty, privacy: .public) \(detail, privacy: .public) text=\(text, privacy: .private)"
+        )
+        #endif
+    }
+
+    // MARK: - Formatting helpers
+
+    /// Sample count → seconds at the canonical 16 kHz ASR rate.
+    public static func seconds(samples: Int, sampleRate: Int = 16_000) -> String {
+        guard sampleRate > 0 else { return "0.00" }
+        return String(format: "%.2f", Double(samples) / Double(sampleRate))
+    }
+
+    public static func seconds(since start: Date) -> String {
+        String(format: "%.2f", Date().timeIntervalSince(start))
+    }
+
+    /// Root-mean-square of a PCM window — distinguishes "user was silent"
+    /// from "audio never reached the recogniser" when a transcript is empty.
+    public static func rms(_ samples: [Float]) -> String {
+        guard !samples.isEmpty else { return "0.0000" }
+        var sum: Float = 0
+        for sample in samples {
+            sum += sample * sample
+        }
+        return String(format: "%.4f", (sum / Float(samples.count)).squareRoot())
+    }
+}