Files
chanora/docs/governance/product-decision-register.md
T
EdisonJwa 9790005c3e feat(beta): wire voice in/out end-to-end with push-to-talk (v0.2.0-beta.1)
Reaches the Internal Beta milestone of DEC-001's release sequence the
same day as Alpha. Adds voice capture and playback through the full
Flutter UI → FRB → Rust core → tsclientlib → server path.

Promotions from PoC:
  poc/audio-capture-playback-spike  →  crates/chanora_audio/

New product code:
  crates/chanora_audio/src/engine.rs — cpal capture and playback,
    audiopus Opus VoIP encoder (48 kHz mono 20 ms frames), tsclientlib
    AudioHandler for decode + jitter buffer + mix on playback,
    push-to-talk gate, graceful playback-only fallback when capture
    is unavailable.
  crates/chanora_protocol/src/adapter.rs — extended with
    voice_out_tx (clonable mpsc::Sender<OutPacket>) and
    take_voice_in() (one-shot mpsc::Receiver<InboundVoice>); main
    loop now interleaves outbound voice drain, event pumping, and
    control-request handling.
  crates/chanora_protocol/src/lib.rs — re-exports the few
    tsproto_packets types (OutAudio, OutPacket, InAudioBuf,
    AudioData, CodecType, Direction) that chanora_audio
    legitimately needs. Documented as the single deliberate
    cross-crate type re-export per SAD-067, justified by the
    performance cost of a parallel type hierarchy on the 20 ms
    voice frame.
  core/chanora_core/src/lib.rs — ChanoraSession::start_audio,
    set_ptt, audio_stats; disconnect now stops the engine first.
  crates/chanora_bridge/src/api.rs — startAudio, setPtt,
    audioStats commands and BridgeAudioStats DTO.
  apps/chanora_flutter/lib/main.dart — "Start audio" button +
    hold-to-talk PTT button with pressed/released visual state +
    live stats line (TX/RX/PTT). Stats polled every 500 ms.

ARB:
  Both en and zh-Hans gain startAudioAction, pttHoldToTalk,
  pttTransmitting, audioStatsLine. Banner updated to
  "Beta build — voice in/out wired; not production ready."

FRB config:
  flutter_rust_bridge.yaml gains local: true so codegen resolves
  the workspace member's library stem to "chanora_bridge" instead
  of falling back to "UNKNOWN".

Empirical verification (2026-05-14, against cn.teamspeak.app):
  cargo check + cargo test --workspace: all green.
  flutter analyze: 0 issues.
  flutter test: 4/4 passing including:
    - test/alpha_e2e_test.dart (regression: Alpha still works)
    - test/beta_e2e_test.dart (Beta: connect → startAudio →
      PTT cycle → disconnect against cn.teamspeak.app).
  Live smoke (cargo test alpha_smoke -- --ignored): 49 channels,
  37 clients retrieved.
  Capture stream open against the host PipeWire auto_null source
  refused (snd_pcm_hw_params); engine correctly logged the warning
  and continued in playback-only mode. TX=0 frames, RX=0 frames
  reflects the headless null-source environment; on a real mic
  host the encoder produces ~50 frames/second while PTT is held.

Honest Beta scope (NOT in this release):
  - AEC / AGC / NS / HPF DSP (DEC-007..010): AudioEffects exists
    as a struct but the filters are no-ops. Beta+ work.
  - Production-quality resampler: current code is linear
    interpolation. Beta+ work.
  - Identity persistence via chanora_storage: still ephemeral.
  - Push-to-Dart event stream: UI polls instead.
  - chanora_diagnostics tracing-layer wiring: still scaffold.
  - Mobile (Android) cdylib + UI: PoC-proven, not yet in product.
  - Reconnect / network-loss recovery for the voice path.

Docs updates:
  - docs/governance/product-decision-register.md bumped to v0.9.7
    (Beta-milestone change-history entry; no row changes).
  - docs/governance/poc-results-summary.md bumped to v0.6.0
    (RISK-PoC-005 updated with Beta progress).
2026-05-14 22:43:57 +08:00

23 KiB

CHANORA_CFG_Product_Decision_Register_v0.9.7.0.0

Document type: Configuration / Product Decision Register
Version: 0.9.7
Status: Baseline Candidate
Language: English
Product: Chanora
Repo path: docs/governance/product-decision-register.md ---

1. Purpose

This document records key product, architecture, release, legal, and engineering decisions that affect Chanora scope, testing, architecture, app store eligibility, and release readiness.

A decision marked Proposed / Owner Confirmation Required is a recommended decision that should be confirmed by the owner before Final / Approved Baseline.

2. Decision Status Legend

Status Meaning
Proposed / Owner Confirmation Required Recommended decision; owner must confirm before Final.
Accepted Confirmed and part of baseline.
Deferred Not decided for this release; must not block scope if explicitly deferred.
Rejected Not selected.

3. Key Blocking Decisions

Decision ID Decision Recommended decision Status Owner Why it matters
DEC-001 Release type Internal Alpha first, then External Beta, then MVP Public / Store Release Accepted Product Owner Controls release gate, verification bar, legal/privacy requirements, and platform scope.
DEC-002 MVP platform scope MVP target remains Windows, macOS, Linux, Android, and iOS; first release may be staged by channel/platform Accepted Product Owner + Engineering Owner Controls verification matrix, build artifacts, store readiness, and support load.
DEC-003 Minimum iOS version iOS 13 minimum for Flutter support baseline; test latest iOS release separately Accepted Product Owner + iOS Owner Controls iOS compatibility, test devices, and app store eligibility.
DEC-004 Minimum Android version Android API 28 (Android 9.0) minimum, raised from the original recommendation of API 24 by explicit owner ruling on 2026-05-14. Rationale: simplifies the audio path (AAudio is unconditionally available from API 26+ and stable from API 28), narrows the TLS / privacy / scoped-storage compatibility surface, and matches typical 2026 Android baselines. The cpal-on-Oboe Android spike was built with minSdk = 24 and cargo-ndk -P 26; product code in apps/chanora_flutter must move minSdk to 28 and may simplify the AAudio-vs-OpenSL-ES fallback logic accordingly. Accepted Product Owner + Android Owner Controls Android device support, runtime permissions, and Play Store eligibility.
DEC-005 Android target SDK Target the Google Play-required API level on the upload date; current release gate uses API 35+ unless newer Google policy applies Accepted Android Owner + Release Manager Required for new apps and updates submitted to Google Play after the current policy date.
DEC-006 Multiple server connections in MVP Not in MVP; support one active server connection per client instance Accepted Product Owner + Software Architect Reduces state synchronization, audio routing, UI complexity, and verification scope.
DEC-007 AEC default state Enabled by default on platforms/audio backends where supported and stable Accepted Audio Owner + Product Owner Affects echo quality, CPU usage, platform behavior, and user experience.
DEC-008 AGC default state Enabled by default, with user setting to disable Accepted Audio Owner + Product Owner Affects perceived loudness consistency and may affect advanced user preference.
DEC-009 Noise suppression default state Enabled by default, with user setting to disable Accepted Audio Owner + Product Owner Improves typical voice quality but may affect voice naturalness and CPU usage.
DEC-010 High-pass filter default state Enabled by default Accepted Audio Owner Removes low-frequency rumble and usually improves speech capture.
DEC-011 Audio processing implementation path Use platform-native audio processing first where available; use Rust/WebRTC-style processing as controlled fallback or later architecture option Accepted Software Architect + Audio Owner Controls architecture, latency, CPU use, platform compatibility, and testing.
DEC-011.1 Audio crate choice cpal for desktop (empirically verified on Linux/PipeWire by poc/audio-capture-playback-spike on 2026-05-13) and for Android (cpal-on-Oboe, empirically verified on a Motorola Moto G Stylus 5G (2023) running Android 14 arm64-v8a by poc/audio-capture-playback-android-spike on 2026-05-13); iOS crate TBD pending an iOS spike that requires macOS + Xcode hardware Accepted (desktop + Android) / Deferred (iOS) Software Architect + Audio Owner Pins the desktop and Android audio dependencies; iOS remains an open risk surface.
DEC-012 Official SDK / trademark / licensing review Public/store release is blocked until legal confirms TeamSpeak non-affiliation wording, trademark usage, OSS licenses, and tsclientlib license posture Accepted (as a release gate) Legal / Compliance + Product Owner Public release risk and store metadata risk. Owner accepted the gate on 2026-05-14; the legal review itself is still to be performed and remains a public-release blocker.
DEC-013 Local database choice Use SQLite or equivalent embedded local database for non-secret local state; secrets remain in platform secure storage Accepted Software Architect + Storage Owner Controls storage schema, migrations, backup/delete policy, and portability.
DEC-013.1 SQLite crate rusqlite with the bundled feature (SQLite statically linked into the binary; no system libsqlite3 dependency); verified by poc/sqlite-storage-spike on 2026-05-13 Accepted Software Architect + Storage Owner Pins the embedded-DB dependency; locks reproducibility.
DEC-013.2 Linux secure-storage backend policy Prefer Secret Service (libsecret / gnome-keyring / kwallet / KeePassXC) on Linux; if the default collection is locked or D-Bus is unavailable, fall back to kernel keyutils with a clear user notice. Both backends are "equivalent" per SysRS-053 / SysRS-162; verified by poc/secure-storage-spike on 2026-05-13 Accepted Software Architect + Storage Owner + Security Reviewer Closes the SysRS-162 ambiguity surfaced by the secure-storage PoC.
DEC-014 Bridge choice Use a stable typed Flutter/Rust bridge with generated or schema-controlled DTOs; flutter_rust_bridge 2.x pinned (empirically verified at 2.12.0 by poc/flutter_rust_bridge_hello on 2026-05-13) Accepted Software Architect Controls API stability, maintainability, async event flow, and long-term code generation.
DEC-015 Product language for MVP English + Chinese (Simplified) for MVP, raised from the original recommendation of English-only by explicit owner ruling on 2026-05-14. Rationale: the demonstrated test-server population (verified live against cn.teamspeak.app) and broader TS3 audience include substantial Chinese-speaking users; shipping zh-Hans alongside en at MVP avoids a launch-window UX gap. Architecture remains i18n-ready so additional languages can be added later mechanically. Server-provided content is preserved verbatim and never translated (ADR-008 UTF-8 boundary, DEC-015 server-content rule retained). Accepted Product Owner Controls localization scope and release schedule.
DEC-016 Diagnostics upload policy No automatic upload for MVP; user-initiated local diagnostic export only Accepted Product Owner + Legal + Security Controls privacy policy, support workflow, and security review scope.
DEC-017 Crash reporting Disabled for MVP unless explicit opt-in provider and privacy policy are approved Accepted Product Owner + Legal + Security Avoids privacy/legal complexity before public release.
DEC-018 Public product name Chanora Accepted Product Owner Branding and legal identity. Trademark / registrability check remains under DEC-012 legal review before public release.
DEC-019 Public non-affiliation statement Use legal-approved wording; drafted text accepted as working copy: "Chanora is independent and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak." Subject to final legal review under DEC-012 before public release. Accepted (drafted wording) Legal / Compliance Required for public release and store metadata.
DEC-021 Apple App Store submission SDK Use Xcode 26 or later and the iOS 26 / iPadOS 26 SDK or later for App Store submission on or after 2026-04-28, unless Apple publishes a newer applicable requirement before upload Accepted iOS Owner + Release Manager Controls App Store Connect upload eligibility and release pipeline.
DEC-020 License model Dual-licensed under Apache-2.0 OR MIT (recipient's choice), the standard Rust-ecosystem permissive license model. Accepted on 2026-05-14. Compatible with every direct dependency in the PoC tree (tsclientlib MIT-OR-Apache-2.0, flutter_rust_bridge MIT, cpal Apache-2.0, rusqlite MIT, keyring MIT-OR-Apache-2.0, etc.) and with the Flutter framework's BSD-3-Clause. The license texts ship as LICENSE-APACHE and LICENSE-MIT at the repository root; an aggregator LICENSE points to both. NOTICE enumerates current direct-dependency attributions. The full OSS legal review (transitive deps, license obligations, OSS notices) remains under DEC-012 and is still required before public release. Accepted Product Owner + Legal Business and OSS compliance decision. No longer a public-release blocker by itself; legal review under DEC-012 is the remaining gate.
DEC-022 Canonical implementation directory layout Accept the README's sketch as canonical: apps/chanora_flutter/, core/chanora_core/, crates/chanora_protocol/, crates/chanora_audio/, crates/chanora_state/, crates/chanora_storage/, crates/chanora_diagnostics/, crates/chanora_bridge/. Matches SAD §7.2 module decomposition Accepted Software Architect Unblocks product-crate scaffolding; was not formalised by any prior doc.

4. Accepted MVP Defaults

The "Recommended" defaults below have all been confirmed by the owner; two were modified from the original recommendation (marked MODIFIED).

Area Accepted MVP default
Release sequence Internal Alpha → External Beta → MVP Public
MVP platforms Windows, macOS, Linux, Android, iOS (staged release allowed)
Active connections One active server connection
UI design system Material 3 + Chanora Design System
Product language MODIFIED — English + Chinese (Simplified) at MVP; i18n-ready architecture
Server content Preserve and display Unicode; do not translate
Diagnostics Local, user-initiated export only
Telemetry None
Crash reporting None unless later approved
Secret storage Platform secure storage
Non-secret local storage SQLite (rusqlite bundled)
Audio processing Platform-native first; fallback strategy documented
AEC Enabled by default where supported
AGC Enabled by default (user-toggleable)
Noise suppression Enabled by default (user-toggleable)
High-pass filter Enabled by default
Android minimum MODIFIED — API 28 (Android 9.0), raised from the original recommendation of API 24
Android target API 35 or newer per current Google Play policy on upload date
iOS minimum iOS 13
Apple App Store SDK gate Xcode 26+ / iOS 26 SDK+ for uploads on or after 2026-04-28
Audio crate cpal (desktop, Android); iOS deferred
Bridge Stable typed Flutter/Rust bridge; flutter_rust_bridge 2.x pinned
Implementation directory layout apps/chanora_flutter/, core/chanora_core/, crates/chanora_*
License Dual-licensed under Apache-2.0 OR MIT, recipient's choice (DEC-020)

5. Decision Impact Matrix

Decision Affects SysRS Affects SysDes Affects SRS Affects SAD Affects SDD Affects Verification Affects Release
Minimum iOS / Android versions Yes Yes Yes Yes Yes Yes Yes
Android target SDK No No Yes No No Yes Yes
Multiple active connections Yes Yes Yes Yes Yes Yes Yes
AEC/AGC/NS/HPF defaults Yes Yes Yes Yes Yes Yes Yes
Audio implementation path No if behavior unchanged Yes Possibly Yes Yes Yes Yes
SDK/trademark/legal review Yes No No No No Yes Yes
SQLite/equivalent choice Possibly Yes Yes Yes Yes Yes Yes
Bridge choice No if API behavior unchanged Yes Possibly Yes Yes Yes Yes
Apple App Store SDK gate Yes Yes Yes Yes Yes Yes Yes
Diagnostics upload policy Yes Yes Yes Yes Yes Yes Yes
Crash reporting Yes if included Yes if included Yes if included Yes if included Yes if included Yes Yes

6. Decisions That Must Be Confirmed By You

All decisions in the register have been addressed by the owner. The remaining release-gating work (not decisions) is the legal review itself under DEC-012, which must complete before any public/store release but is not an open decision:

Priority Item Status
P0 DEC-012 legal/trademark/licensing review — perform the actual review work (non-affiliation wording final sign-off, trademark registrability check, transitive-dependency OSS obligations, tsclientlib license posture confirmation). Pending; gate Accepted.

7. Open Decision Log

Decision ID Owner Decision Status Date Notes
DEC-001 Product Owner Release type sequence Accepted 2026-05-14 Internal Alpha → External Beta → MVP Public.
DEC-002 Product Owner / Engineering MVP platform strategy Accepted 2026-05-14 All five platforms as target; staged release allowed.
DEC-003 Product Owner / iOS Owner Minimum iOS version Accepted 2026-05-14 iOS 13.
DEC-004 Product Owner / Android Owner Minimum Android version Accepted 2026-05-14 API 28 (modified from the recommendation of API 24).
DEC-005 Android Owner / Release Manager Android target SDK Accepted 2026-05-14 Google Play-required API on upload date (currently API 35+).
DEC-006 Product Owner / Software Architect Multiple server connections in MVP Accepted 2026-05-14 Single connection in MVP.
DEC-007 Audio Owner / Product Owner AEC default Accepted 2026-05-14 Enabled by default where supported.
DEC-008 Audio Owner / Product Owner AGC default Accepted 2026-05-14 Enabled by default with user toggle.
DEC-009 Audio Owner / Product Owner Noise suppression default Accepted 2026-05-14 Enabled by default with user toggle.
DEC-010 Audio Owner High-pass filter default Accepted 2026-05-14 Enabled by default.
DEC-011 Software Architect / Audio Owner Audio processing path Accepted 2026-05-14 Platform-native first; Rust/WebRTC-style fallback.
DEC-011.1 Software Architect / Audio Owner Audio crate (desktop / mobile) Accepted (desktop: cpal; Android: cpal-on-Oboe) / Deferred (iOS) 2026-05-13 Closed by poc/audio-capture-playback-spike (desktop) and poc/audio-capture-playback-android-spike (Android). iOS crate TBD pending iOS spike.
DEC-012 Legal / Compliance SDK/trademark/licensing review Accepted as a release gate 2026-05-14 Required before public/store release; legal review work still to be performed.
DEC-013 Software Architect / Storage Owner Local database Accepted 2026-05-14 SQLite or equivalent for non-secret state.
DEC-013.1 Software Architect / Storage Owner SQLite crate Accepted (rusqlite bundled) 2026-05-13 Closed by poc/sqlite-storage-spike 11/11.
DEC-013.2 Software Architect / Storage Owner / Security Reviewer Linux secure-storage backend policy Accepted (Secret Service preferred, keyutils fallback) 2026-05-13 Closed by poc/secure-storage-spike 6/6. Resolves SysRS-053 / SysRS-162 ambiguity.
DEC-014 Software Architect Bridge choice Accepted (flutter_rust_bridge 2.x pinned) 2026-05-13 Closed by poc/flutter_rust_bridge_hello 3/3.
DEC-015 Product Owner Product language for MVP Accepted 2026-05-14 English + Chinese (Simplified) (modified from the recommendation of English-only).
DEC-016 Product Owner / Legal / Security Diagnostics upload policy Accepted 2026-05-14 User-initiated local export only; no automatic upload.
DEC-017 Product Owner / Legal / Security Crash reporting Accepted 2026-05-14 Disabled for MVP.
DEC-018 Product Owner Public product name Accepted 2026-05-14 Chanora. Trademark check still required under DEC-012.
DEC-019 Legal / Compliance Public non-affiliation statement Accepted (drafted wording) 2026-05-14 Final legal sign-off still required under DEC-012.
DEC-020 Product Owner / Legal License model Accepted (Apache-2.0 OR MIT dual-license) 2026-05-14 Compatible with every direct dependency; texts ship as LICENSE-APACHE / LICENSE-MIT. Full OSS legal review remains under DEC-012.
DEC-021 iOS Owner / Release Manager Apple App Store SDK gate Accepted 2026-05-14 Xcode 26+ / iOS 26 SDK+ on or after 2026-04-28.
DEC-022 Software Architect Canonical implementation directory layout Accepted (README sketch) 2026-05-13 Closes the absence flagged during PoC review.

8. Change History

Version Date Description
0.9.0 2026-05-14 Updated decision register with proposed decisions for mobile minimum versions, audio defaults, audio implementation path, legal review, local database, bridge choice, diagnostics policy, and MVP release scope.

Baseline Candidate 0.9.1 Update

Version Date Description
0.9.1 2026-05-14 Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ for App Store Connect upload on or after 2026-04-28, platform baselines and decision traceability propagated across the document set.

Baseline Candidate 0.9.2 Update

Version Date Description
0.9.2 2026-05-14 Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage.

Baseline Candidate 0.9.3 Update

Version Date Description
0.9.3 2026-05-14 Recorded owner-confirmed decisions surfaced during the initial PoC phase: DEC-014 Accepted (flutter_rust_bridge 2.x pinned); added DEC-011.1 Accepted for desktop (cpal) / Deferred for mobile; added DEC-013.1 Accepted (rusqlite bundled); added DEC-013.2 Accepted (Linux Secret Service preferred with keyutils fallback); added DEC-022 Accepted (canonical implementation directory layout per README sketch and SAD §7.2); DEC-020 explicitly Deferred and remains a public-release blocker. Evidence pointers: poc/flutter_rust_bridge_hello/VERIFICATION.md, poc/secure-storage-spike/VERIFICATION.md, poc/sqlite-storage-spike/VERIFICATION.md, poc/audio-capture-playback-spike/VERIFICATION.md.

Baseline Candidate 0.9.4 Update

Version Date Description
0.9.4 2026-05-14 Promoted DEC-011.1 mobile half from Deferred to Accepted (Android), keeping iOS Deferred. Evidence: poc/audio-capture-playback-android-spike/VERIFICATION.md records empirical playback (22,050 frames at 44.1 kHz mono out of the device speaker) and capture (42,624 frames written to a valid 85,292-byte RIFF/WAVE mono 16-bit PCM file) on a physical Motorola Moto G Stylus 5G (2023) running Android 14 arm64-v8a, verifying the full Rust → cpal → Oboe → AAudio → Android audio HAL path.

Baseline Candidate 0.9.5 Update

Version Date Description
0.9.5 2026-05-14 Owner confirmation pass on all previously-Proposed decisions. Accepted: DEC-001, DEC-002, DEC-003, DEC-005, DEC-006, DEC-007, DEC-008, DEC-009, DEC-010, DEC-011, DEC-012 (as a release gate), DEC-013, DEC-015, DEC-016, DEC-017, DEC-018, DEC-019 (drafted wording), DEC-021. Two decisions modified from their original recommendations: DEC-004 Android minimum raised from API 24 to API 28 (simpler audio path, narrower compatibility surface); DEC-015 product language expanded from English-only to English + Chinese (Simplified) for MVP (reflects the demonstrated TS3-compatible-server audience). DEC-020 license model remains Open / Deferred — the only public-release blocker outstanding. §4 renamed from "Recommended MVP Defaults" to "Accepted MVP Defaults" with MODIFIED rows annotated. §6 collapsed to the single remaining DEC-020 item. §7 dated and statused.

Baseline Candidate 0.9.6 Update

Version Date Description
0.9.6 2026-05-14 DEC-020 license model closed: Apache-2.0 OR MIT dual-license (standard Rust-ecosystem permissive model). The license is compatible with every direct dependency in the PoC tree (tsclientlib, flutter_rust_bridge, cpal, rusqlite, keyring, hound, etc.) and with the Flutter framework's BSD-3-Clause. License texts added as LICENSE-APACHE and LICENSE-MIT at the repository root; the existing LICENSE file now aggregates both with the dual-license declaration and the standard Apache-2.0 inbound-contribution clause. NOTICE populated with current direct-dependency attributions. README §License rewritten. §4 updated. §6 collapsed: there is no longer any open decision — DEC-012 legal review remains a pending work item, not a pending decision. With this change, every previously-Proposed or Open decision in the register has been resolved; the only outstanding release-gating activity is the DEC-012 legal review itself (which is sign-off work, not an architectural choice).

Baseline Candidate 0.9.7 Update

Version Date Description
0.9.7 2026-05-14 DEC-001 release-sequence progress recorded: Internal Alpha (v0.1.0-alpha.1, commit 3bb038c) completed on 2026-05-14; Internal Beta first build (v0.2.0-beta.1) reached the same day. Beta milestone adds voice in/out: crates/chanora_audio promoted from scaffold to a cpal-based capture + playback engine with audiopus Opus encoding and tsclientlib AudioHandler for decode + jitter buffer + mix; crates/chanora_protocol extended to forward inbound voice packets and accept outbound OutPackets via mpsc channels; core/chanora_core::ChanoraSession exposes start_audio, set_ptt, and audio_stats; crates/chanora_bridge adds matching DTOs; the Flutter UI gains a "Start audio" action and a hold-to-talk PTT button with live frame counters. Verified end-to-end against cn.teamspeak.app; capture runs in graceful playback-only mode on hosts with no usable microphone (e.g. the PipeWire auto_null source on the verification host). No decision rows change; this entry documents progress against DEC-001 only.