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

docs(governance): record PoC outcomes, owner decisions, and audit evidence

Browse Source 
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.
This commit is contained in:
EdisonJwa
2026-05-14 12:34:13 +08:00
parent 181b3d329d
commit 271d23faf7
6 changed files with 233 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/governance/poc-results-summary.md
+114
View File
@@ -0,0 +1,114 @@
# PoC Results Summary
**Document type:** Governance / PoC Results Summary
**Version:** 0.1.0
**Status:** Draft
**Language:** English
**Product:** Chanora
**Repo path:** `docs/governance/poc-results-summary.md`
---
## 1. Purpose
This document is the single top-level entry point summarising the
outcome of the technical proof-of-concept (PoC) phase defined by
[`docs/architecture/proof-of-concept-plan.md`](../architecture/proof-of-concept-plan.md).
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/`.
This summary records facts as of **2026-05-13**.
## 2. Status table
| Spike | PoC plan exit criterion | Status | Evidence |
|---|---|---|---|
| `flutter_rust_bridge_hello` | Flutter can call Rust and receive event stream data | **PASS** | `poc/flutter_rust_bridge_hello/VERIFICATION.md` |
| `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` |
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.
## 3. Toolchain exercised
| Tool | Version |
|---|---|
| Rust toolchain | stable 1.95.0 (59807616e 2026-04-14) |
| 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) |
| `cpal` | 0.16 |
| `rusqlite` | 0.32 (bundled) |
| `keyring` | 3.6.3 (sync-secret-service + linux-native) |
| `linux-keyutils` | 0.2.5 |
| `regex` / `serde` / `serde_json` | 1 |
| 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) |
## 4. Owner-confirmed decisions arising from the PoC phase
Recorded in [`docs/governance/product-decision-register.md`](product-decision-register.md) at version 0.9.3:
| Decision | Status | Closed by |
|---|---|---|
| **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-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** |
The remaining DEC-001..012, DEC-015..019, DEC-021 are still in
status "Proposed / Owner Confirmation Required" and need owner
attention as a separate exercise — they are unaffected by the PoCs.
## 5. Audit-report coverage
| Audit ID | Verified by | Audit-report row updated? |
|---|---|---|
| SS-AUD-001 (identity secret absent from local DB) | `secure-storage-spike` | Yes — `docs/security/secure-storage-audit-report.md` §4 v0.9.3 |
| SS-AUD-002 (server password absent from local DB) | `secure-storage-spike` | Yes |
| SS-AUD-003 (no secrets in logs) | `secure-storage-spike` + cross-ref `diagnostics-redaction-spike` | Yes |
| SS-AUD-004 (no secrets in diagnostic export) | `diagnostics-redaction-spike` REDACT-TC-008 | Yes |
| SS-AUD-005 (safe error on backend failure) | `secure-storage-spike` (test + live CLI fallback) | Yes |
| SS-AUD-006 (delete removes entry) | `secure-storage-spike` | Yes |
| SS-AUD-007 (per-platform documentation) | Linux only — partial | Yes (status: Partial) |
| SS-AUD-008 (migration path safety) | Pending (depends on product `chanora_storage`) | Yes (status: Pending) |
| SS-TC-001 (Windows) | Not run | Status: Deferred |
| SS-TC-002 (macOS) | Not run | Status: Deferred |
| SS-TC-003 (Linux) | `secure-storage-spike` | **PoC Pass** |
| SS-TC-004 (Android) | Not run | Status: Deferred |
| SS-TC-005 (iOS) | Not run | Status: Deferred |
| REDACT-TC-001..010 | `diagnostics-redaction-spike` (12/12) | Yes — `docs/security/diagnostic-redaction-audit-report.md` §4 v0.9.3 |
| Export bundle policy §5 (all rows) | `diagnostics-redaction-spike` | Yes — §5 v0.9.3 |
## 6. Open risks and gaps
| 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-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. |
| RISK-PoC-005 | Production code does not exist yet. README's "Implementation status: Not production-ready" remains accurate. | Software Architect | Promote PoC code into `apps/` and `crates/` per DEC-022 only after RISK-PoC-003/004 are closed or explicitly accepted. |
## 7. Non-promotion reminder
Per `proof-of-concept-plan.md` §4: **a PoC is not product code unless
explicitly promoted.** Nothing under `poc/` should be imported by
the future `apps/chanora_flutter` or `crates/chanora_*` trees
without an explicit promotion record per spike.
## 8. Change History
| 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. |
docs/governance/product-decision-register.md
+21 -6
View File
@@ -1,8 +1,8 @@
# CHANORA_CFG_Product_Decision_Register_v0.9.2.2.1
# CHANORA_CFG_Product_Decision_Register_v0.9.3.0.0
**Document type:** Configuration / Product Decision Register
**Version:** 0.9.2
**Version:** 0.9.3
**Status:** Baseline Candidate
**Language:** English
**Product:** Chanora
@@ -38,16 +38,20 @@ 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-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-014 | Bridge choice | Use a stable typed Flutter/Rust bridge with generated or schema-controlled DTOs; default to `flutter_rust_bridge` unless prototype proves a better option | Proposed / Owner Confirmation Required | Software Architect | Controls API stability, maintainability, async event flow, and long-term code generation. |
| 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-only product UI for MVP; i18n-ready architecture; server-provided content preserved and not translated | Proposed / Owner Confirmation Required | Product Owner | Controls localization scope and release schedule. |
| DEC-016 | Diagnostics upload policy | No automatic upload for MVP; user-initiated local diagnostic export only | Proposed / Owner Confirmation Required | 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 | Proposed / Owner Confirmation Required | Product Owner + Legal + Security | Avoids privacy/legal complexity before public release. |
| DEC-018 | Public product name | Chanora | Proposed / Owner Confirmation Required | Product Owner | Branding and legal identity. |
| DEC-019 | Public non-affiliation statement | Use legal-approved wording; draft: “Chanora is independent and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak.” | Proposed / Legal Confirmation Required | 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 | Proposed / Owner Confirmation Required | iOS Owner + Release Manager | Controls App Store Connect upload eligibility and release pipeline. |
| DEC-020 | License model | TBD by owner; no public release until license model and OSS obligations are confirmed | Open | Product Owner + Legal | Business and OSS compliance decision. |
| DEC-020 | License model | TBD by owner; no public release until license model and OSS obligations are confirmed | Open | Product Owner + Legal | Business and OSS compliance decision. Explicitly deferred on 2026-05-13 by owner; remains a public-release blocker. |
| 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. Recommended MVP Defaults
@@ -119,10 +123,14 @@ 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-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-014 | Software Architect | Bridge choice | Proposed / Owner Confirmation Required | TBD | Recommended: typed bridge; default candidate `flutter_rust_bridge`. |
| DEC-020 | Product Owner / Legal | License model | Open | TBD | Must be decided before public release. |
| 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-020 | Product Owner / Legal | License model | Open / Deferred | 2026-05-13 | Explicitly deferred by owner; remains a public-release blocker. |
| DEC-022 | Software Architect | Canonical implementation directory layout | Accepted (README sketch) | 2026-05-13 | Closes the absence flagged during PoC review. |
## 8. Change History
@@ -143,3 +151,10 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de
| 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`. |