diff --git a/CHANGELOG.md b/CHANGELOG.md index 782bc2d..2da9530 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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: diff --git a/docs/architecture/proof-of-concept-plan.md b/docs/architecture/proof-of-concept-plan.md index 66718d5..11623e0 100644 --- a/docs/architecture/proof-of-concept-plan.md +++ b/docs/architecture/proof-of-concept-plan.md @@ -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. | diff --git a/docs/governance/poc-results-summary.md b/docs/governance/poc-results-summary.md index fc93df0..7ea4848 100644 --- a/docs/governance/poc-results-summary.md +++ b/docs/governance/poc-results-summary.md @@ -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. | diff --git a/docs/governance/product-decision-register.md b/docs/governance/product-decision-register.md index 2470ad3..c877790 100644 --- a/docs/governance/product-decision-register.md +++ b/docs/governance/product-decision-register.md @@ -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. | diff --git a/poc/README.md b/poc/README.md index c4ac5a9..5b73947 100644 --- a/poc/README.md +++ b/poc/README.md @@ -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 diff --git a/poc/audio-capture-playback-spike/VERIFICATION.md b/poc/audio-capture-playback-spike/VERIFICATION.md index 8bbdcee..dfe8cb8 100644 --- a/poc/audio-capture-playback-spike/VERIFICATION.md +++ b/poc/audio-capture-playback-spike/VERIFICATION.md @@ -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`.