diff --git a/docs/architecture/sdd.md b/docs/architecture/sdd.md index 536d9c1..b47ae90 100644 --- a/docs/architecture/sdd.md +++ b/docs/architecture/sdd.md @@ -65,6 +65,8 @@ Design rules: | Transmit control | `TransmitMode` supports `Ptt`, `Continuous`, and reserved `VoiceActivity`; `VoiceActivity` has no active MVP implementation | | PTT | Desktop/mobile backends expose capability level and active backend; missed-key-up watchdog prevents stuck transmit | | Release tail | Tail handling prevents abrupt cutoffs after PTT release where configured | +| Render peak limiter | `voice_render::limit_peak_inplace` is a single-pass, allocation-free per-frame peak scaler applied in both the macOS and iOS render callbacks before the i16 downmix; default threshold 0.99 prevents hard clipping on multi-client mixes that sum past 0 dBFS while remaining transparent for normal voice levels (allocation-free, lock-free, safe on the realtime audio thread) | +| VPIO ducking config (macOS 14+) | `ios_voice_unit.rs` writes an 8-byte `AuVoiceIoOtherAudioDuckingConfiguration` struct (`m_enable_advanced_ducking = 0` disables dynamic voice-activity-driven ducking; `m_ducking_level = kAUVoiceIOOtherAudioDuckingLevelMin = 10`) to selector `kAUVoiceIOProperty_OtherAudioDuckingConfiguration` (= 2108) on the VoiceProcessingIO AudioUnit at startup, minimising the ducking of other apps' audio during a voice session; on macOS 13 the property is silently ignored (VPIO returns the default ducking behaviour) and the code logs a debug message and continues | | Benchmarks | Realtime capture, Opus, and resampler benchmarks provide advisory baseline evidence | ## 6. Storage and Secret Design diff --git a/docs/governance/product-decision-register.md b/docs/governance/product-decision-register.md index 8c49e2e..143cfc8 100644 --- a/docs/governance/product-decision-register.md +++ b/docs/governance/product-decision-register.md @@ -16,6 +16,7 @@ This register records product and engineering decisions referenced by the DV doc | DEC-027 desktop mouse side-button PTT | Accepted by requirements baseline | Verification must not over-claim unsupported platform input classes | | DEC-030 VAD deferral | Accepted as deferral | `VoiceActivity` remains disabled/coming-soon | | DEC-032 Android CMake patch exit path | Active tracking | Patched dependency requires reevaluation | +| DEC-033 macOS VPIO ducking configuration | Accepted | Write `kAUVoiceIOProperty_OtherAudioDuckingConfiguration` with `mEnableAdvancedDucking=0` (disables dynamic voice-activity-driven ducking) and `mDuckingLevel=Min` (= 10) to minimise the ducking of other apps' audio during a voice session; property is macOS 14+ only, the macOS 13 set fails silently (debug log) and VPIO uses its default behaviour; matches the iOS `.voiceChat` baseline on macOS 14+ | ## 3. DV Rule diff --git a/docs/sysrs.md b/docs/sysrs.md index 7fcd503..599605f 100644 --- a/docs/sysrs.md +++ b/docs/sysrs.md @@ -500,7 +500,7 @@ External compatible server - Priority: P0 - Verification: Test -**SysRS-051**: The macOS runtime environment shall provide microphone permission prompts, microphone capture, speaker/headphone playback, audio device selection, and Keychain access to the Chanora application. +**SysRS-051**: The macOS runtime environment shall provide microphone permission prompts, microphone capture, speaker/headphone playback, audio device selection, and Keychain access to the Chanora application. Note: macOS has no AVAudioSession-equivalent surface; the macOS audio lifecycle in the current baseline is limited to launch-time microphone permission (`AVCaptureDevice.requestAccess`), the VPIO engine restart on Core Audio HAL default-device change (`kAudioHardwarePropertyDefaultInputDevice` / `DefaultOutputDevice` listeners), and the VPIO startup readback at engine start. Full audio route change + interruption handling — as available on iOS via AVAudioSession observers in `apps/chanora_flutter/ios/Runner/AppDelegate.swift` — is not present in the current macOS baseline; closing the gap is DEC-level scope, not a P0-MVP item. - Priority: P0 - Verification: Test @@ -1959,10 +1959,10 @@ This section converts the baseline product decisions into auditable system-level - Priority: P0 - Verification: Review (SysDes/SAD declaration of tolerance value is present and is referenced by the CI workflow definition) -**SysRS-310**: The Chanora application system shall support macOS runtime deployment on macOS 10.15 (Catalina) or later as the minimum supported runtime, unless Flutter, plugin, audio, or platform constraints require raising the minimum version. This clause ratifies at the SysRS layer the existing macOS baseline already encoded in `apps/chanora_flutter/macos/chanora_bridge.podspec` (`MACOSX_DEPLOYMENT_TARGET = 10.15`) and provides explicit cross-platform-baseline coverage parallel to SysRS-286 (iOS) and SysRS-288 (Android). Rationale: macOS 10.15 is the floor that supports the modern CoreAudio / AVAudioEngine voice-processing-IO surfaces relied on by the realtime audio path, native arm64 Apple Silicon builds (no Rosetta dependence), and the SDK version used by the existing podspec lipo step that produces the universal binary; a lower minimum would require backporting audio code paths or shipping a non-universal build, neither of which is in P0-MVP scope. The minimum may be raised further (for example, to macOS 11.0 / Big Sur for native Apple Silicon performance gains) only via a superseding accepted decision recorded as a DEC entry; it shall not be lowered without a superseding accepted decision. Cross-references: SAD-087 (architectural macOS runtime allocation), SDD-119 (macOS bridge build pipeline consuming this baseline), SysRS-286 (iOS minimum runtime parallel), SysRS-288 (Android minimum runtime parallel). ID-allocation note: this clause uses SysRS-310 rather than the structurally parallel SysRS-290 because SysRS-290 is already allocated (MVP single-active-server-connection scope); monotonic numbering convention is preserved. +**SysRS-310**: The Chanora application system shall support macOS runtime deployment on macOS 13.0 (Ventura) or later as the minimum supported runtime, unless Flutter, plugin, audio, or platform constraints require raising the minimum version. This clause ratifies at the SysRS layer the existing macOS baseline already encoded in `apps/chanora_flutter/macos/chanora_bridge.podspec` (`MACOSX_DEPLOYMENT_TARGET = 13.0`) and provides explicit cross-platform-baseline coverage parallel to SysRS-286 (iOS) and SysRS-288 (Android). Rationale: macOS 13.0 is the floor that supports the modern CoreAudio / VoiceProcessingIO surfaces relied on by the realtime audio path, native arm64 Apple Silicon builds (no Rosetta dependence), and the SDK version used by the existing podspec lipo step that produces the universal binary; a lower minimum would require backporting audio code paths or shipping a non-universal build, neither of which is in P0-MVP scope. The minimum may be raised further (for example, to macOS 14 / Sonoma to gain the `kAUVoiceIOProperty_OtherAudioDuckingConfiguration` AudioUnit property) only via a superseding accepted decision recorded as a DEC entry; it shall not be lowered without a superseding accepted decision. Cross-references: SAD-087 (architectural macOS runtime allocation), SDD-119 (macOS bridge build pipeline consuming this baseline), SysRS-286 (iOS minimum runtime parallel), SysRS-288 (Android minimum runtime parallel). ID-allocation note: this clause uses SysRS-310 rather than the structurally parallel SysRS-290 because SysRS-290 is already allocated (MVP single-active-server-connection scope); monotonic numbering convention is preserved. - Priority: P0 -- Verification: Review (the SysRS baseline matches the podspec `MACOSX_DEPLOYMENT_TARGET` setting), Platform Test (the produced macOS binary runs on a macOS 10.15 system) +- Verification: Review (the SysRS baseline matches the podspec `MACOSX_DEPLOYMENT_TARGET` setting), Platform Test (the produced macOS binary runs on a macOS 13.0 system) ## 32. Change History Addendum @@ -2005,3 +2005,10 @@ This section converts the baseline product decisions into auditable system-level |---|---|---| | 0.9.11 | 2026-05-18 | Closed the Wave 1.5 traceability-audit deferred-but-optional follow-up by adding SysRS-310 (macOS minimum runtime baseline at macOS 10.15 / Catalina), ratifying at SysRS layer the existing `apps/chanora_flutter/macos/chanora_bridge.podspec` `MACOSX_DEPLOYMENT_TARGET = 10.15` setting and providing explicit cross-platform-baseline coverage parallel to SysRS-286 (iOS) and SysRS-288 (Android). Allocated SysRS-310 rather than SysRS-290 because SysRS-290 is already taken (MVP single-active-server-connection scope); monotonic numbering convention preserved. No change to the numeric baseline value; any future raise (e.g., to macOS 11.0 / Big Sur for native Apple Silicon performance gains) is flagged as a DEC-level change, not authored here. | | 0.9.10 | 2026-05-18 | Authorized Option B of the benchmark-infrastructure decision for the realtime audio path. Added SysRS-307 (maintained numeric performance baselines for the realtime audio capture and playback paths — heap allocation count per callback after warmup, per-callback wall-clock budget relative to the audio frame period, Opus encode/decode latency, and resampler throughput at common rate-pair conversions; extends SysRS-180/SysRS-181 from prescriptive intent into a measurable contract; consistent with SysRS-186 and SysRS-236). Added SysRS-308 (advisory CI regression reporting executing the benchmark suite on every PR and every merge to the default branch on at least one host architecture, surfacing results in the PR status-check view; explicitly **advisory only** — does not fail the build, does not block merge; escalation to a build-failing hard gate is out of scope and deferred to a future SysRS clause after baseline maturity; consistent with the SysRS-234..239 verification-family pattern). Added SysRS-309 (explicitly declared numeric tolerance window for the advisory comparison; numeric value(s) and comparison methodology delegated to SysDes/SAD; suggested starting value +20% recorded as non-binding downstream guidance). All three new clauses are consistent with SysRS-295 (no automatic telemetry / diagnostic upload in MVP) — they neither authorize nor require off-device transmission of measurement data beyond the existing CI provider surface visible to repository collaborators. Explicitly **NOT** authored in this update: (a) Dimension 3 production telemetry export of timing histograms (deferred to P1; any future opt-in performance-evidence export through the user-initiated diagnostic-export path requires a separate P1 SysRS clause and must be reconciled with SysRS-295 at that time); (b) build-failing hard CI gate (deferred to a future SysRS clause). | + + +## Baseline Candidate 0.9.12 Update + +| Version | Date | Description | +|---|---|---| +| 0.9.12 | 2026-06-07 | Raised the macOS minimum runtime baseline in `SysRS-310` from macOS 10.15 (Catalina) to macOS 13.0 (Ventura) to match the actual floor encoded in `apps/chanora_flutter/macos/chanora_bridge.podspec` (`MACOSX_DEPLOYMENT_TARGET = 13.0`) and `apps/chanora_flutter/macos/macos_deployment_target.rb`. The previous 10.15 text was a documentation lag; no behavioural change, no DEC-level raise, and the podspec + Xcode project are unchanged. macOS 13.0 is the floor that supports native arm64 Apple Silicon without Rosetta, modern CoreAudio / VoiceProcessingIO surfaces, and the podspec lipo step that produces the universal binary. Strict layered sourcing preserved (`SysDes -> SysRS` only). |