edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(governance): promote audio PoC to PASS; close mobile-Android half

Browse Source 
Documentation update following the Android audio spike pass.

Decision register (v0.9.3 → v0.9.4):
  - DEC-011.1 promoted from
      'Accepted (desktop: cpal) / Deferred (mobile)'
    to
      'Accepted (desktop: cpal; Android: cpal-on-Oboe) / Deferred (iOS)'.
  - Evidence pointer added: poc/audio-capture-playback-android-spike/
    VERIFICATION.md.

PoC plan (v0.2.0 → v0.3.0):
  - Audio row promoted from PARTIAL PASS to PASS.
  - All six PoC plan entries are now PASS.

PoC results summary (v0.1.0 → v0.2.0):
  - Audio row collapsed into one PASS spanning both spikes.
  - RISK-PoC-001 narrowed from 'mobile audio' to 'iOS audio only'.
  - Toolchain table expanded with Android NDK, cargo-ndk, AGP/
    Gradle/Kotlin, jni/ndk-context/android_logger, and the test
    device.

Cross-spike pointers updated:
  - poc/audio-capture-playback-spike/VERIFICATION.md result and
    follow-up sections updated to reference the Android spike.
  - poc/README.md status table lists both audio spike directories.

CHANGELOG updated under [Unreleased].
This commit is contained in:
EdisonJwa
2026-05-14 18:25:03 +08:00
parent ec21a880d2
commit 4c64517e45
6 changed files with 72 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+24 -2
View File
@@ -32,13 +32,35 @@ This project is expected to follow a Conventional Commits style workflow.
redaction. Audit cases REDACT-TC-001..010 verified on 2026-05-13.
- `poc/audio-capture-playback-spike/` — PoC proving platform audio
capture/playback via cpal. Desktop half (Linux + PipeWire)
empirically verified end-to-end on 2026-05-13; mobile half
(Android Oboe / iOS AVAudioEngine) documented as an open gap.
empirically verified end-to-end on 2026-05-13; mobile half closed
separately by `poc/audio-capture-playback-android-spike`.
- `poc/audio-capture-playback-android-spike/` — PoC closing the
mobile half of the audio capture/playback PoC plan entry. Rust
cdylib + JNI + Kotlin Android app; cpal targets Android's Oboe
backend (AAudio). Verified end-to-end on a physical Motorola
Moto G Stylus 5G (2023) running Android 14 arm64-v8a on
2026-05-13: 500 ms 440 Hz sine wave driven out the device speaker
(22,050 frames at 44.1 kHz) and 1 s captured from the microphone
into a valid 85,292-byte RIFF/WAVE mono 16-bit PCM file pulled via
`adb exec-out run-as`.
- `poc/README.md` summarising PoC status against
`docs/architecture/proof-of-concept-plan.md`.
### Changed
- `docs/architecture/proof-of-concept-plan.md` bumped to v0.3.0 to
promote the audio PoC from PARTIAL PASS to PASS after the Android
mobile half was closed; all six PoC plan entries are now PASS.
- `docs/governance/product-decision-register.md` bumped to v0.9.4 to
promote DEC-011.1 mobile half from Deferred to Accepted (Android),
keeping iOS Deferred.
- `docs/governance/poc-results-summary.md` bumped to v0.2.0:
audio row promoted to PASS, RISK-PoC-001 narrowed from "mobile
audio" to "iOS audio only", Android toolchain added to the
toolchain table.
- `poc/audio-capture-playback-spike/VERIFICATION.md` updated to point
at the Android spike for the mobile half.
- `poc/README.md` updated to list both audio spike directories.
- `docs/architecture/proof-of-concept-plan.md` bumped to v0.2.0 to
record PoC outcomes (5 PASS, 1 PARTIAL) and add a Status column.
- `docs/security/secure-storage-audit-report.md` bumped to v0.9.3:
docs/architecture/proof-of-concept-plan.md
+3 -2
View File
@@ -1,7 +1,7 @@
# Proof-of-Concept Plan
**Document type:** Architecture / Proof-of-Concept Plan
**Version:** 0.2.0
**Version:** 0.3.0
**Status:** Draft
**Language:** English
**Product:** Chanora
@@ -19,7 +19,7 @@ This document defines technical proof-of-concept work that should be completed b
|---|---|---|---|
| Flutter/Rust bridge hello | Prove command/result/event DTO boundary | Flutter can call Rust and receive event stream data | **PASS** — `poc/flutter_rust_bridge_hello/VERIFICATION.md` (Linux desktop, 3/3 tests, 2026-05-13). Closes DEC-014. |
| `tsclientlib` connect spike | Prove protocol feasibility | Rust can connect to a compatible server/test double | **PASS** — `poc/tsclientlib-connect-spike/VERIFICATION.md` (live against `cn.teamspeak.app`, 2026-05-13). |
| Audio capture/playback spike | Prove platform audio behavior | Capture/playback works on at least one desktop and one mobile target | **PARTIAL PASS** — `poc/audio-capture-playback-spike/VERIFICATION.md`. Desktop half met on Linux/PipeWire (2026-05-13). Mobile half NOT verified; remains an open gap. Closes DEC-011.1 for desktop only. |
| Audio capture/playback spike | Prove platform audio behavior | Capture/playback works on at least one desktop and one mobile target | **PASS** — desktop half: `poc/audio-capture-playback-spike/VERIFICATION.md` (Linux/PipeWire, 2026-05-13). Mobile half: `poc/audio-capture-playback-android-spike/VERIFICATION.md` (Android 14 arm64-v8a on a physical Motorola Moto G Stylus 5G, 2026-05-13). Closes DEC-011.1 for desktop + Android; iOS still Deferred. |
| Secure storage spike | Prove secret storage behavior | Secret write/read/delete works through platform secure storage | **PASS (Linux only)** — `poc/secure-storage-spike/VERIFICATION.md` (6/6 audit tests, 2026-05-13). Closes DEC-013.2 (Linux backend policy). |
| SQLite storage spike | Prove local non-secret persistence | Schema, migration, and repository pattern are demonstrated | **PASS** — `poc/sqlite-storage-spike/VERIFICATION.md` (11/11 tests, 2026-05-13). Closes DEC-013.1. |
| Diagnostics redaction spike | Prove redaction before export | Password and identity-secret samples are redacted | **PASS** — `poc/diagnostics-redaction-spike/VERIFICATION.md` (REDACT-TC-001..010, 2026-05-13). |
@@ -48,3 +48,4 @@ A PoC is not product code unless explicitly promoted.
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial proof-of-concept plan. |
| 0.2.0 | 2026-05-14 | Recorded PoC outcomes: 5 PASS, 1 PARTIAL PASS (mobile half of audio still open). Added Status column. Spike directories live under `poc/`; see `poc/README.md` and `docs/governance/poc-results-summary.md`. |
| 0.3.0 | 2026-05-14 | Audio PoC promoted from PARTIAL PASS to PASS after `poc/audio-capture-playback-android-spike` verified the mobile half on a physical Android device. All six PoC plan entries are now PASS. iOS is explicitly deferred per DEC-011.1 and remains an open follow-up but is no longer a PoC-plan gap. |
docs/governance/poc-results-summary.md
+17 -8
View File
@@ -1,7 +1,7 @@
# PoC Results Summary
**Document type:** Governance / PoC Results Summary
**Version:** 0.1.0
**Version:** 0.2.0
**Status:** Draft
**Language:** English
**Product:** Chanora
@@ -17,7 +17,7 @@ outcome of the technical proof-of-concept (PoC) phase defined by
It exists so that reviewers (security, audit, baseline-approval) can
read one page and follow pointers to evidence, rather than having to
crawl six `VERIFICATION.md` files under `poc/`.
crawl seven `VERIFICATION.md` files under `poc/`.
This summary records facts as of **2026-05-13**.
@@ -29,18 +29,20 @@ This summary records facts as of **2026-05-13**.
| `tsclientlib-connect-spike` | Rust can connect to a compatible server/test double | **PASS** | `poc/tsclientlib-connect-spike/VERIFICATION.md` |
| `secure-storage-spike` | Secret write/read/delete works through platform secure storage | **PASS (Linux only)** | `poc/secure-storage-spike/VERIFICATION.md` |
| `sqlite-storage-spike` | Schema, migration, and repository pattern are demonstrated | **PASS** | `poc/sqlite-storage-spike/VERIFICATION.md` |
| `diagnostics-redaction-spike` | Password and identity-secret samples are redacted | **PASS** (REDACT-TC-001..010 covered) | `poc/diagnostics-redaction-spike/VERIFICATION.md` |
| `audio-capture-playback-spike` | Capture/playback works on at least one desktop **and** one mobile target | **PARTIAL PASS** — desktop met, mobile **not** verified | `poc/audio-capture-playback-spike/VERIFICATION.md` |
| `diagnostics-redaction-spike` | Password and identity-secret samples are redacted (REDACT-TC-001..010 covered) | **PASS** | `poc/diagnostics-redaction-spike/VERIFICATION.md` |
| `audio-capture-playback-spike` (desktop half) + `audio-capture-playback-android-spike` (mobile half) | Capture/playback works on at least one desktop **and** one mobile target | **PASS** — desktop on Linux + PipeWire; mobile on a physical Motorola Moto G Stylus 5G running Android 14 arm64-v8a. iOS remains explicitly deferred per DEC-011.1. | `poc/audio-capture-playback-spike/VERIFICATION.md`, `poc/audio-capture-playback-android-spike/VERIFICATION.md` |
Aggregate test count across the PoCs: **44 tests + 1 live-server CLI
run + 1 audio-stack CLI round-trip**, all passing in the recorded
runs.
run + 1 desktop-audio CLI round-trip + 1 Android playback + 1 Android
capture (real-device, with WAV file inspection)**, all passing in the
recorded runs. **All six PoC plan entries now PASS.**
## 3. Toolchain exercised
| Tool | Version |
|---|---|
| Rust toolchain | stable 1.95.0 (59807616e 2026-04-14) |
| Rust Android targets | aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android, i686-linux-android |
| Flutter SDK | 3.41.9 stable (Dart 3.11.5) |
| `flutter_rust_bridge` (Rust + Dart) and codegen | 2.12.0 |
| `tsclientlib` | git `04aa2491` (no published crates.io release) |
@@ -49,9 +51,15 @@ runs.
| `keyring` | 3.6.3 (sync-secret-service + linux-native) |
| `linux-keyutils` | 0.2.5 |
| `regex` / `serde` / `serde_json` | 1 |
| Android SDK | platform 34, build-tools 34.0.0 |
| Android NDK | r26.3.11579264 |
| `cargo-ndk` | 4.1.2 |
| AGP / Gradle / Kotlin | 8.5.2 / 8.7 / 1.9.24 |
| `jni`, `ndk-context`, `android_logger` | 0.21, 0.1.1, 0.14 |
| Host OS for verification | Linux (Arch, kernel 7.0.5-arch1-1, x86_64) |
| Host audio server | PipeWire 1.6.4 (via pcm_pipewire ALSA plugin) |
| Host Secret Service backend | gnome-keyring (default collection observed locked; kernel keyutils backend used for hermetic tests) |
| Android test device | Motorola Moto G Stylus 5G (2023), Android 14 (SDK 34), arm64-v8a |
## 4. Owner-confirmed decisions arising from the PoC phase
@@ -62,7 +70,7 @@ Recorded in [`docs/governance/product-decision-register.md`](product-decision-re
| **DEC-014** typed bridge | Accepted (`flutter_rust_bridge` 2.x pinned) | `flutter_rust_bridge_hello` |
| **DEC-013.1** SQLite crate | Accepted (`rusqlite` bundled) | `sqlite-storage-spike` |
| **DEC-013.2** Linux secure-storage backend policy | Accepted (Secret Service preferred, keyutils fallback) | `secure-storage-spike` |
| **DEC-011.1** audio crate | Accepted (desktop: `cpal`) / Deferred (mobile) | `audio-capture-playback-spike` (desktop half only) |
| **DEC-011.1** audio crate | Accepted (desktop: `cpal`; Android: `cpal`-on-Oboe) / Deferred (iOS) | `audio-capture-playback-spike` (desktop) + `audio-capture-playback-android-spike` (mobile) |
| **DEC-022** canonical implementation directory layout | Accepted (README sketch — `apps/chanora_flutter/`, `core/chanora_core/`, `crates/chanora_*`) | Owner ruling on 2026-05-13 |
| **DEC-020** license | Open / Deferred | Owner deferred 2026-05-13 — **remains a public-release blocker** |
@@ -94,7 +102,7 @@ attention as a separate exercise — they are unaffected by the PoCs.
| ID | Risk | Owner | Recommended close path |
|---|---|---|---|
| RISK-PoC-001 | Mobile audio (Android Oboe / iOS AVAudioEngine) is not verified. The PoC plan's audio exit criterion is only half met. | Audio Owner + Mobile Owner | Spike on Android emulator and iOS device before `chanora_audio` is scaffolded; or accept the risk and discover it during product integration (not recommended). |
| RISK-PoC-001 | iOS audio (AVAudioEngine via cpal or a per-platform iOS adapter) is not verified. The desktop and Android halves of the PoC plan's audio criterion are met; iOS is explicitly deferred per DEC-011.1. | Audio Owner + iOS Owner | iOS spike on macOS + Xcode hardware; or accept the risk and discover it during product integration (not recommended). |
| RISK-PoC-002 | Windows / macOS / iOS / Android secure-storage adapters not implemented. SS-TC-001/002/004/005 unverified. | Platform Owners | Per-platform adapter spike or first-implementation-in-`chanora_storage` with the audit checks re-run on each target. |
| RISK-PoC-003 | License (DEC-020) deferred. Blocks public/store release. | Product Owner + Legal | Owner ruling. |
| RISK-PoC-004 | DEC-001..012, 015..019, 021 still in Proposed status. They do not block PoC code but do block any baseline-approval gate. | Product Owner | Independent owner review of the decision register. |
@@ -112,3 +120,4 @@ without an explicit promotion record per spike.
| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial PoC results summary. Records the outcome of the first PoC batch (5 PASS, 1 PARTIAL), the toolchain versions exercised, the owner-confirmed decisions, audit-report coverage, and the open risks. |
| 0.2.0 | 2026-05-14 | Audio PoC promoted from PARTIAL to PASS after the Android spike verified the mobile half on a physical Motorola Moto G Stylus 5G running Android 14 arm64-v8a. All six PoC plan entries now PASS. RISK-PoC-001 narrowed from "mobile audio" to "iOS audio only". Android toolchain (NDK r26.3, cargo-ndk, AGP/Gradle/Kotlin, jni/ndk-context/android_logger) added to the toolchain table. |
docs/governance/product-decision-register.md
+11 -4
View File
@@ -1,8 +1,8 @@
# CHANORA_CFG_Product_Decision_Register_v0.9.3.0.0
# CHANORA_CFG_Product_Decision_Register_v0.9.4.0.0
**Document type:** Configuration / Product Decision Register
**Version:** 0.9.3
**Version:** 0.9.4
**Status:** Baseline Candidate
**Language:** English
**Product:** Chanora
@@ -38,7 +38,7 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de
| DEC-009 | Noise suppression default state | Enabled by default, with user setting to disable | Proposed / Owner Confirmation Required | 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 | Proposed / Owner Confirmation Required | 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 | Proposed / Owner Confirmation Required | 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 by `poc/audio-capture-playback-spike` on 2026-05-13); mobile crate(s) TBD pending Android/iOS spike | Accepted (desktop) / Deferred (mobile) | Software Architect + Audio Owner | Pins the desktop audio dependency; mobile remains an open risk surface. |
| 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 | Proposed / Owner Confirmation Required | Legal / Compliance + Product Owner | Public release risk and store metadata risk. |
| DEC-013 | Local database choice | Use SQLite or equivalent embedded local database for non-secret local state; secrets remain in platform secure storage | Proposed / Owner Confirmation Required | 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. |
@@ -123,7 +123,7 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de
| DEC-009 | Audio Owner / Product Owner | Noise suppression default | Proposed / Owner Confirmation Required | TBD | Recommended: enabled. |
| DEC-010 | Audio Owner | High-pass filter default | Proposed / Owner Confirmation Required | TBD | Recommended: enabled. |
| DEC-011 | Software Architect / Audio Owner | Audio processing path | Proposed / Owner Confirmation Required | TBD | Recommended: platform-native first. |
| DEC-011.1 | Software Architect / Audio Owner | Audio crate (desktop / mobile) | Accepted (desktop: `cpal`) / Deferred (mobile) | 2026-05-13 | Closed by `poc/audio-capture-playback-spike` for desktop. Mobile crate TBD pending mobile spike. |
| 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 | Proposed / Owner Confirmation Required | TBD | Required before public/store release. |
| DEC-013 | Software Architect / Storage Owner | Local database | Proposed / Owner Confirmation Required | TBD | Recommended: SQLite or equivalent. |
| DEC-013.1 | Software Architect / Storage Owner | SQLite crate | Accepted (`rusqlite` bundled) | 2026-05-13 | Closed by `poc/sqlite-storage-spike` 11/11. |
@@ -158,3 +158,10 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de
| 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. |
poc/README.md
+2 -1
View File
@@ -16,9 +16,10 @@ Authority: [`docs/architecture/proof-of-concept-plan.md`](../docs/architecture/p
| `tsclientlib-connect-spike` | yes | **PASS** — see `tsclientlib-connect-spike/VERIFICATION.md` |
| `flutter_rust_bridge_hello` | yes (`flutter-rust-bridge-hello` in plan) | **PASS** — see `flutter_rust_bridge_hello/VERIFICATION.md` |
| `secure-storage-spike` | yes | **PASS (Linux only)** — see `secure-storage-spike/VERIFICATION.md` |
| `audio-capture-playback-spike` | yes | **PARTIAL PASS** — desktop verified, mobile not — see `audio-capture-playback-spike/VERIFICATION.md` |
| `sqlite-storage-spike` | yes | **PASS** — see `sqlite-storage-spike/VERIFICATION.md` |
| `diagnostics-redaction-spike` | yes | **PASS** — see `diagnostics-redaction-spike/VERIFICATION.md` |
| `audio-capture-playback-spike` (desktop half) | yes | **PASS** — see `audio-capture-playback-spike/VERIFICATION.md` |
| `audio-capture-playback-android-spike` (mobile half) | yes | **PASS** — see `audio-capture-playback-android-spike/VERIFICATION.md` |
## Naming note
poc/audio-capture-playback-spike/VERIFICATION.md
+15 -10
View File
@@ -2,15 +2,14 @@
## Result
**PARTIAL PASS.** Desktop half met on Linux; **mobile half not
verified**.
**PASS (desktop half).** The Linux/PipeWire desktop half of the PoC
plan §2 audio exit criterion is fully met by this spike.
The PoC plan §2 exit criterion is "Capture/playback works on at least
one desktop and one mobile target." This spike has empirically
verified the **desktop** path (Linux × cpal × PipeWire). The
**mobile** path (Android Oboe or iOS AVAudioEngine) has not been
built or run in this session and remains a documented gap. See the
`Gaps` section in `README.md`.
The mobile half ("at least one mobile target") is closed by
[`poc/audio-capture-playback-android-spike`](../audio-capture-playback-android-spike/)
on a physical Android device — see that directory's `VERIFICATION.md`.
Combined: the audio PoC is fully retired.
## Environment
@@ -112,7 +111,13 @@ consumed by the platform audio stack.
1. Promote `cpal` selection to a recorded product decision (DEC-011
sub-decision) — or pin a different crate after the mobile spike.
Done on 2026-05-13 as DEC-011.1 in
`docs/governance/product-decision-register.md`.
2. Spike Android Oboe path on an emulator or real device.
Done on 2026-05-13 — see
`poc/audio-capture-playback-android-spike/VERIFICATION.md`.
3. Spike iOS AVAudioEngine path on a real device.
4. Only after the mobile half is closed: promote the typed
`AudioError` + capture/playback shapes into `chanora_audio`.
Still deferred; requires macOS + Xcode hardware.
4. Only after the iOS half is closed (or explicitly waived):
promote the typed `AudioError` + capture/playback shapes into
`chanora_audio`.