8094ec7277545e82dbdab7f3b4852beacc4c2830
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 EdisonJwa
|
8094ec7277 |
docs(release): add Windows build instructions + PowerShell helper
The development host is Linux x86_64; `flutter build windows` cannot
be cross-compiled and requires a Windows host with Visual Studio
2022's C++ Desktop workload. This commit adds the instructions for
producing the Windows v0.2.0-beta.1 Internal Beta build on an Azure
VM, plus a PowerShell helper that automates the build itself.
docs/release/windows-build.md (v0.1.0):
- Toolchain pin table (Windows Server 2022, VS 2022 Build Tools
+ C++ workload, Flutter 3.41.9, Rust 1.95 stable, FRB 2.12.0,
CMake, audiopus build dependency).
- Azure VM provisioning recipe: Standard_D4s_v5 (4 vCPU / 16 GiB),
Premium SSD 128 GiB, RDP locked to caller IP, auto-shutdown,
cost estimate (<USD 1 per build session).
- Step-by-step PowerShell to install VS 2022 Build Tools with the
required components, Git for Windows, rustup, Flutter SDK,
flutter_rust_bridge_codegen, and CMake.
- Two upload paths for source: temporary git remote OR zip archive
over RDP clipboard.
- flutter create --platforms=windows to scaffold the
windows/ platform folder (the product Flutter app was created
with only linux + android).
- cargo build -p chanora_bridge to produce chanora_bridge.dll.
- flutter build windows --release to produce chanora_flutter.exe
and the bundle.
- Drop the DLL next to the EXE so dart:ffi loads it.
- Smoke-test instructions including the cn.teamspeak.app UDP 9987
egress gotcha for some Azure regions.
- Packaging into chanora-v0.2.0-beta.1-windows-x64.zip.
- Known-issue / caveat table.
- Reproducibility note (build is not bit-reproducible in this Beta).
tools/build-windows.ps1:
- Parameter switches: -SkipRustBuild, -RegenerateBindings, -Version.
- Verifies flutter, cargo, rustc, cmake, git on PATH.
- Adds the x86_64-pc-windows-msvc target via rustup if missing.
- Runs flutter create --platforms=windows if the windows/ folder
is absent in apps/chanora_flutter/.
- Optionally regenerates FRB bindings.
- cargo build --release -p chanora_bridge --target x86_64-pc-windows-msvc.
- flutter pub get + flutter build windows --release.
- Copies the DLL into the Release bundle.
- Compress-Archive into chanora-<version>-windows-x64.zip.
- Prints final artefact paths.
This is documentation + helper only; no actual Windows binaries are
produced by this commit. To produce the binaries, follow §3-§13 of
docs/release/windows-build.md on a Windows host.
|
||
|
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).
|
||
|
EdisonJwa
|
53b176b722 |
docs(governance): record Alpha milestone in PoC results summary (v0.5.0)
Updates RISK-PoC-005 to 'partially closed' and adds a v0.5.0 change
history entry documenting:
- the tsclientlib spike promotion into crates/chanora_protocol;
- the typed ChanoraSession in core/chanora_core wiring the
protocol API;
- the FRB 2.12.0 bridge wiring;
- the Flutter Alpha UI;
- the empirical verification path through alpha_e2e_test.dart
and alpha_smoke.rs;
- the v0.1.0-alpha.1 tag pointing at commit 3bb038c.
No other doc bumps are needed: the decision register stays at v0.9.6
(no new decisions), the audit reports stay at v0.9.3 (no new audit
evidence beyond what the PoCs already provided), the PoC plan stays
at v0.3.0 (all six PoC entries were already PASS).
|
||
|
EdisonJwa
|
e0f34009d9 |
docs(governance): record product scaffolding paths (DEC-022)
Updates two documents to reflect the workspace + Flutter app
scaffold landed in the previous commit.
path-migration-map.md v0.9.2 -> v0.9.3:
Adds §3 Implementation Path Layout. Lists each subsystem's
canonical crate path alongside its SAD / SysDes / DEC authority.
Notes that the Flutter app is owned by Flutter tooling and is
not a Cargo workspace member.
CHANGELOG entry under [Unreleased]:
- Documents the seven new Cargo workspace members and the
invariants pinned at the workspace level.
- Documents the Flutter app scaffold, the DEC-004 minSdk = 28
override, and the DEC-015 English + Simplified Chinese ARB
catalogue (with the ADR-008 server-content reaffirmation).
- Records the empirical verification (cargo check + cargo test
+ flutter analyze + flutter test all clean).
|
||
|
EdisonJwa
|
0f418f1d7e |
feat(legal): resolve DEC-020 — dual-license under Apache-2.0 OR MIT
Closes the only previously-open decision in the register. Chanora is
now dual-licensed under either:
* Apache License, Version 2.0 (LICENSE-APACHE), OR
* MIT License (LICENSE-MIT)
at the recipient's option. This is the standard Rust-ecosystem
permissive model and is 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
hound Apache-2.0
ndk-context, jni, android_logger, regex, serde, tokio,
tracing, thiserror, zeroize, etc. MIT OR Apache-2.0
and with the Flutter framework's BSD-3-Clause.
Files added:
- LICENSE-APACHE Apache 2.0 license text.
- LICENSE-MIT MIT license text with the standard 2026 copyright
line.
Files updated:
- LICENSE Now the dual-license aggregator. Includes the standard
Apache-2.0 inbound-contribution clause ("Unless you
explicitly state otherwise, any contribution
intentionally submitted for inclusion in Chanora by you,
as defined in the Apache-2.0 license, shall be
dual-licensed as above, without any additional terms or
conditions.").
- NOTICE Rewritten with the dual-license declaration and an
inventory of direct dependencies with their upstream
licenses. Transitive deps remain to be enumerated by
build tooling (cargo about, Flutter LicenseRegistry).
- README.md §License section rewritten to point at LICENSE-APACHE
and LICENSE-MIT.
- docs/governance/product-decision-register.md v0.9.5 → v0.9.6:
DEC-020 status: Open → Accepted. §4 license row updated. §6
collapsed: every previously-Proposed or Open decision in the
register is now resolved. DEC-012 legal review remains as a
release-gating *work* item, but is not an open decision.
- docs/governance/poc-results-summary.md v0.3.0 → v0.4.0:
RISK-PoC-003 closed. DEC-020 row moved out of 'Still open'.
This is a license-model commitment, not a substitute for the
DEC-012 legal review. Per DEC-012 the actual legal review work
(transitive-dep OSS obligations, trademark registrability, final
sign-off on the non-affiliation wording) must still be completed
before any public/store release; that is sign-off work, not an
architectural decision.
Decision register state after this commit:
Accepted: 23 of 23 unique decisions
Open/Deferred: 0
Proposed: 0
|
||
|
EdisonJwa
|
a0d1c35461 |
docs(governance): owner confirmation on remaining 17 decisions (register v0.9.5)
Closes the 'Proposed / Owner Confirmation Required' state for every
decision in the register except DEC-020 (license, explicitly deferred
and now the only public-release-gating decision outstanding).
Accepted as recommended:
DEC-001 (Alpha → Beta → Public release sequence),
DEC-002 (all five platforms as MVP target, staged release allowed),
DEC-003 (iOS minimum: iOS 13),
DEC-005 (Android target SDK: Play-required API on upload date),
DEC-006 (single active server connection in MVP),
DEC-007/008/009/010 (AEC + AGC + NS + HPF defaults),
DEC-011 (platform-native audio first),
DEC-012 (legal/trademark/licensing review as a release gate),
DEC-013 (SQLite or equivalent for non-secret state),
DEC-016 (no automatic diagnostics upload),
DEC-017 (crash reporting disabled for MVP),
DEC-018 (product name: Chanora),
DEC-019 (drafted non-affiliation wording),
DEC-021 (Apple App Store SDK gate: Xcode 26+ / iOS 26 SDK+ on/after 2026-04-28).
Modified from the original recommendation by explicit owner ruling:
- DEC-004: Android minimum raised to API 28 (Android 9.0) from the
recommended API 24. Rationale: simpler audio path (AAudio stable
from API 28), narrower compatibility / privacy / scoped-storage
surface. Affects the Android spike's minSdk=24 in product code:
apps/chanora_flutter will need minSdk=28.
- DEC-015: MVP product language expanded to English + Chinese
(Simplified) from the recommended English-only. Rationale: the
demonstrated TS3-compatible-server audience (verified live against
cn.teamspeak.app) and broader TS3 audience include substantial
Chinese-speaking users. Adds zh-Hans translation, font, and
text-length-budget work to MVP. Server-provided content is still
preserved verbatim per ADR-008.
Still Open / Deferred:
- DEC-020 license model. The only remaining release-gating decision.
Documentation updates:
- product-decision-register.md → v0.9.5. §3 statuses updated, §4
renamed Recommended → Accepted with MODIFIED rows annotated,
§6 collapsed to DEC-020 only, §7 dated and statused for every
decision, change-history entry added.
- poc-results-summary.md → v0.3.0. §4 expanded with the
2026-05-14 owner-confirmation pass table. RISK-PoC-004 closed.
New RISK-PoC-006 (Android minSdk move 24 → 28) and RISK-PoC-007
(MVP language expansion to en + zh-Hans) added.
- CHANGELOG entry under [Unreleased].
|
||
|
EdisonJwa
|
4c64517e45 |
docs(governance): promote audio PoC to PASS; close mobile-Android half
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].
|
||
|
EdisonJwa
|
271d23faf7 |
docs(governance): record PoC outcomes, owner decisions, and audit evidence
Closes Phases A and D of the post-PoC sequencing.
Decision register (v0.9.2 → v0.9.3):
- DEC-014 Accepted: flutter_rust_bridge 2.x pinned (closed by
poc/flutter_rust_bridge_hello).
- DEC-013.1 Accepted: rusqlite (bundled) (closed by
poc/sqlite-storage-spike).
- DEC-013.2 Accepted: Linux secure-storage backend policy —
Secret Service preferred, keyutils fallback (closed by
poc/secure-storage-spike; resolves SysRS-053 / SysRS-162
ambiguity).
- DEC-011.1 Accepted (desktop: cpal) / Deferred (mobile)
(closed by poc/audio-capture-playback-spike desktop half only).
- DEC-022 Accepted: canonical implementation directory layout per
the README sketch and SAD §7.2.
- DEC-020 explicitly Deferred by owner; remains a public-release
blocker.
Audit reports updated with empirical evidence:
- docs/security/secure-storage-audit-report.md v0.9.3:
SS-AUD-001/002/003/005/006 = PoC Pass with evidence pointers;
SS-TC-003 (Linux) Actual Result populated and Status = PoC Pass;
SS-AUD-004 cross-referenced to diagnostics-redaction PoC;
findings SS-FIND-001 (closed by DEC-013.2), SS-FIND-002 (keyutils
session caveat), SS-FIND-003 (non-Linux adapters still open).
- docs/security/diagnostic-redaction-audit-report.md v0.9.3:
REDACT-TC-001..010 = PoC Pass with evidence pointers; export
bundle policy §5 populated for every row; findings
REDACT-FIND-001 (regex coverage), REDACT-FIND-002
(tracing-layer integration), REDACT-FIND-003 (cross-spike
KnownSecretRegistry contract).
PoC plan (v0.1.0 → v0.2.0):
- Status column added to §2; outcomes recorded.
New doc:
- docs/governance/poc-results-summary.md v0.1.0 — single-page
reviewer-facing summary listing each spike's status, the
toolchain exercised, the owner decisions taken, the audit
coverage table, and open risks RISK-PoC-001..005 (mobile audio,
non-Linux secure-storage adapters, license, remaining
Proposed decisions, no product code yet).
This completes the post-PoC documentation work. Repo is at a clean
pause point: PoC code is committed, owner decisions are recorded,
audit reports carry empirical evidence, and the residual risks are
named in the summary doc.
|
||
|
EdisonJwa
|
f1bc9a6c85 |
chore(repo): initial baseline import (docs v0.9.2 + bootstrap)
Imports the v0.9.2 documentation baseline and the bootstrap files required by docs/governance/repository-bootstrap-plan.md v0.1.0 §3, minus the justfile (added in the next commit). This commit establishes the git history for the project. All previous work lived only as filesystem state with no version control. |