From fbce4db71069377dddcd1f97aa2056152c0584be Mon Sep 17 00:00:00 2001 From: infinityabundance <255699974+infinityabundance@users.noreply.github.com> Date: Thu, 12 Mar 2026 23:24:49 +0000 Subject: [PATCH] Define product core and support posture docs --- README.md | 187 ++++++++++---------- docs/ARCHITECTURE.md | 15 +- docs/CORE_PATH.md | 81 +++++++++ docs/IMPLEMENTATION_STATUS.md | 51 +++--- docs/PRODUCT_CORE.md | 119 +++++++++++++ docs/ROADMAP.md | 12 +- docs/SUPPORT_MATRIX.md | 94 +++++++++++ docs/audits/claims_audit.md | 44 +++++ docs/audits/repository_inventory.md | 59 +++++++ docs/audits/truth_source_conflicts.md | 36 ++++ docs/microtasks.md | 235 ++++++++++++++++++++++++++ 11 files changed, 803 insertions(+), 130 deletions(-) create mode 100644 docs/CORE_PATH.md create mode 100644 docs/PRODUCT_CORE.md create mode 100644 docs/SUPPORT_MATRIX.md create mode 100644 docs/audits/claims_audit.md create mode 100644 docs/audits/repository_inventory.md create mode 100644 docs/audits/truth_source_conflicts.md diff --git a/README.md b/README.md index def47f8..d3a0c80 100644 --- a/README.md +++ b/README.md @@ -24,60 +24,53 @@ --- -## What is RootStream? +## Current Status -RootStream is a **lightweight, encrypted, peer-to-peer game streaming solution** designed specifically for Linux. Design goals include: +RootStream currently supports one primary product path: -- ✅ **No accounts required** - Each device has a unique cryptographic identity -- ✅ **No central servers** - Direct peer-to-peer connections -- ✅ **Minimal compositor dependencies** - Uses kernel DRM/KMS directly when available -- ✅ **Fewer permission popups** - Bypasses PipeWire/portal stack after initial video group setup -- ✅ **Zero-configuration** - Share a QR code, instant connection -- ✅ **Hardware accelerated** - VA-API (Intel/AMD) encoding when available -- ✅ **Low memory footprint** - ~15MB baseline (varies by enabled features) -- ✅ **Strong encryption** - Ed25519 + ChaCha20-Poly1305 (libsodium) +- Linux host via `rootstream host` +- Linux peer via `rootstream connect ` +- direct peer-to-peer networking on a LAN or similarly controlled network +- pairing/bootstrap via `rootstream --qr`, peer codes, and local discovery where available -## Why RootStream? +Repository surfaces such as the KDE client, Windows client, web dashboard, Android, iOS, VR, and infrastructure code exist in-tree, but they are not the default supported product path today. -### The Problem +Start with these truth sources: -Current Linux streaming solutions (Steam Remote Play, Parsec, Sunshine) suffer from: +- [Product Core](docs/PRODUCT_CORE.md) +- [Support Matrix](docs/SUPPORT_MATRIX.md) +- [Core Path](docs/CORE_PATH.md) -| Issue | Steam | Parsec | Sunshine | **RootStream** | -|-------|-------|--------|----------|----------------| -| Requires account | ✗ | ✗ | ✗ | **✓** | -| PipeWire dependency | ✗ | ✗ | ✗ | **✓** (bypasses) | -| Permission dialogs | Constant | Sometimes | Sometimes | **Rarely¹** | -| Compositor resilience | Low | Low | Low | **Higher²** | -| Consumer GPU support | Limited³ | ✓ | ✓ | **Yes⁴** | -| Stream encryption | ✗ | ✗ | ✗ | **✓** | -| Open source | ✗ | ✗ | ✓ | **✓** | +## Not Yet Supported As Defaults -¹ After initial video group membership setup -² Uses kernel-stable DRM/KMS APIs (10+ year stability) -³ NVFBC disabled on GeForce cards -⁴ Intel/AMD via VA-API; NVIDIA via VDPAU wrapper +Do not treat these as part of the current default supported path: -### The Solution +- KDE as the primary desktop client +- Windows as the primary peer platform +- Android or iOS as supported client platforms +- the React dashboard or optional web backend as the default management path +- VR / Proton as part of the supported baseline experience +- cloud-managed or account-based RootStream deployments +- benchmark numbers as settled product guarantees -RootStream takes a **radically different approach**: -``` -Traditional Stack (7+ layers, more failure points): -┌─────────────────────────────────────────────┐ -│ App → Compositor → PipeWire → Portal → │ -│ → Permission Dialog → FFmpeg → Encoder │ -└─────────────────────────────────────────────┘ -Estimated: 30-56ms latency | 500MB memory +## What is RootStream? -RootStream Stack (3 layers, kernel-stable APIs): -┌─────────────────────────────────────────────┐ -│ DRM/KMS → VA-API → ChaCha20-Poly1305 → UDP │ -└─────────────────────────────────────────────┘ -Target: 14-24ms latency | ~15MB memory baseline -``` +RootStream is a Linux-first native peer-to-peer game streaming project. The repository is broader than the current support commitment, so the most important distinction is between what exists in code and what the project currently supports. -> **Note**: Performance numbers are design targets. Actual performance varies by hardware, -> network conditions, and system configuration. See "Reality vs. Claims" section below. +What is evidence-backed today: + +- no required account or hosted control-plane in the supported core path +- native Linux host and peer entrypoints in the root executable +- libsodium-based cryptographic primitives +- QR or peer-code bootstrap for the native flow +- local discovery and backend fallback code in the native runtime + +What is not yet a top-level support commitment: + +- a benchmark-backed latency or memory proof set +- a clean NVIDIA-first product story +- KDE as the default desktop client +- web, mobile, VR, or cloud-managed deployment as equal first-class product lanes --- @@ -96,14 +89,15 @@ Target: 14-24ms latency | ~15MB memory baseline ### 🎮 Optimized for Gaming -- **Low Latency Target** - 14-24ms end-to-end on LAN (varies by hardware and network) -- **High Framerate Support** - Target 60 FPS at 1080p, 30 FPS at 4K (depends on encoder capability) -- **Hardware Acceleration** - VA-API (Intel/AMD) and optional NVENC fallback (NVIDIA) -- **Adaptive Quality** - Prioritizes framerate consistency -- **Input Injection** - Virtual keyboard/mouse via uinput (requires video group membership) +- **Linux-first native runtime** - Host and peer flows exist in the root executable +- **VA-API acceleration path** - Intel/AMD Linux acceleration story is the clearest evidence-backed path today +- **Adaptive and fallback-oriented design** - Multiple capture, discovery, audio, and encode paths exist in the native runtime +- **Input forwarding** - Native input paths exist for the Linux flow +- **Performance targets exist** - Benchmark-backed proof is still being tightened; treat headline numbers as targets rather than settled guarantees ### 🎥 Stream Recording (Phase 18) +- **Current maturity: Preview** - Recording code and CLI exposure exist, but recording is not yet the primary supported product story - **Multi-Codec Support** - H.264 (fast, universal), VP9 (better compression), AV1 (best compression) - **Quality Presets** - Fast, Balanced, High Quality, and Archival modes - **Container Formats** - MP4 (universal compatibility), Matroska/MKV (advanced features) @@ -111,30 +105,23 @@ Target: 14-24ms latency | ~15MB memory baseline - **Smart Storage** - Automatic disk space monitoring and cleanup of old recordings - **Instant Replay** - Save the last N seconds of gameplay (buffer feature) -> **Note**: Recording feature requires FFmpeg libraries. See `src/recording/README.md` for details. - -### 💡 Actually Easy to Use +> **Note**: Recording feature requires FFmpeg libraries. See `src/recording/README.md` for details and treat it as preview rather than the supported default path. -1. **Install RootStream** -```bash - make && sudo make install -``` - -2. **Show your QR code** -```bash - rootstream --qr -``` +### Current Core Workflow -3. **Scan on another device** - - Instant pairing, no typing 44-character keys +1. Build the native Linux binary. +2. Start the host with `rootstream host`. +3. Generate/share host identity with `rootstream --qr`. +4. Connect from another Linux machine with `rootstream connect `. -4. **Auto-connect on LAN** - - mDNS discovery finds peers automatically +See [docs/CORE_PATH.md](docs/CORE_PATH.md) for the canonical path and [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md) for adjacent surfaces that are preview or experimental. --- ## Installation +> **Support note**: The current supported product core is Linux-first. Intel/AMD VA-API is the clearest supported acceleration path today. NVIDIA-related instructions are kept here because the repository contains NVIDIA-oriented code and package assumptions, but they should not be read as a settled support guarantee. + ### Arch Linux #### Dependencies by GPU @@ -183,7 +170,7 @@ vainfo **Expected output:** - **Intel**: `iHD driver` or `i965 driver` - **AMD**: `Radeon` or `AMD Radeon` -- **NVIDIA**: `VDPAU backend` or `nvidia` +- **NVIDIA**: output varies by driver stack; treat NVIDIA results as less settled than the Intel/AMD VA-API path --- @@ -247,7 +234,7 @@ sudo dnf install gcc make libdrm-devel libva-devel gtk3-devel \ ### First Time Setup -1. **Generate your identity** +1. **Generate host identity material** ```bash rootstream --qr ``` @@ -259,23 +246,35 @@ sudo dnf install gcc make libdrm-devel libva-devel gtk3-devel \ ╚══════╝ ``` -2. **Share with another device** - - Scan the QR code with your phone/tablet - - Or copy/paste the text code +2. **Start the Linux host** +```bash +rootstream host +``` + +3. **Connect from the Linux peer** +```bash +rootstream connect +``` -3. **That's it!** - - Devices auto-connect when on same network - - Or manually: `rootstream connect ` +4. **Optional convenience** + - mDNS discovery may help on compatible local networks + - peer-code sharing remains the clearest documented bootstrap path ### Daily Use -**Tray App (Recommended)** +**Canonical supported path** +```bash +rootstream host +rootstream --qr +rootstream connect kXx7Y...@gaming-pc +``` + +**Alternate Linux tray entrypoint** ```bash rootstream ``` -- System tray icon shows status -- Left-click: Show your QR code -- Right-click: Menu (connect, view peers, quit) +- Available when GUI dependencies are present +- Not the canonical path documented in `docs/CORE_PATH.md` **Command Line** ```bash @@ -321,6 +320,7 @@ rootstream --replay-save last30s.mp4 # Save last 30 seconds **Troubleshooting** - See `docs/TROUBLESHOOTING.md` for decode, black screen, input, and dependency diagnostics. +- See `docs/SUPPORT_MATRIX.md` before treating alternate surfaces as supported. **Identity Backup & Restore** RootStream stores identity keys in `~/.config/rootstream/`: @@ -517,7 +517,7 @@ are validated vs. aspirational design targets. - **Compositor crash resilience**: DRM/KMS bypasses compositor in theory, but not extensively tested -- **NVIDIA support**: NVENC backend exists but VDPAU wrapper performance not benchmarked +- **NVIDIA support**: NVIDIA-oriented paths exist, but the repository does not yet present a clean benchmark-backed or support-committed NVIDIA story #### 🎯 Aspirational / Not Fully Validated @@ -528,7 +528,7 @@ are validated vs. aspirational design targets. - **Security audit**: While using audited libraries (libsodium), RootStream's implementation has not undergone independent security audit -- **Cross-platform**: Currently Linux-only; Windows/macOS support is future work +- **Cross-platform**: The supported core is Linux-to-Linux. A Windows client build path exists as preview; broader cross-platform support remains future work - **Perfect forward secrecy**: Session key derivation uses ECDH, but no explicit ephemeral key rotation per-packet @@ -624,19 +624,19 @@ A: They can intercept encrypted packets, but cannot decrypt without your private A: Only for internet streaming. LAN works without port forwarding. **Q: Works over internet?** -A: Yes, but you need to forward UDP port 9876. Consider VPN (Tailscale, ZeroTier) for easier setup. +A: It may work with your own routing or VPN setup, but the current supported path is documented around LAN or similarly controlled private-network use. **Q: Why not just use Steam Remote Play?** -A: Steam requires their servers, uses PipeWire (breaks often), NVFBC disabled on consumer GPUs, no encryption, and constant permission dialogs on Wayland. +A: RootStream is aimed at users who want a Linux-first native P2P path without required accounts. If you need a broader or more polished cross-platform product today, use the tool that fits your environment. **Q: Will this work on my GPU?** -A: Intel/AMD: Yes (VA-API). NVIDIA: Via VDPAU wrapper (slower but works). Run `vainfo` to check. +A: Intel/AMD VA-API is the clearest supported acceleration story today. NVIDIA-related code exists, but the support story is still being cleaned up; see `docs/SUPPORT_MATRIX.md`. **Q: Can I stream to Windows/Mac/Android?** -A: Not yet. Linux-only currently. Cross-platform client planned. +A: The supported core today is Linux-to-Linux. A Windows client build path exists as preview; Android, iOS, web, and VR remain outside the primary supported path. **Q: Is this better than Parsec?** -A: For Linux-to-Linux: Yes (lower latency, no account, encrypted). For other platforms: Use Parsec for now. +A: Different goal. RootStream currently prioritizes a Linux-first native P2P path over broad platform coverage. --- @@ -644,6 +644,9 @@ A: For Linux-to-Linux: Yes (lower latency, no account, encrypted). For other pla For more detailed information, see our documentation: +- **[Product Core](docs/PRODUCT_CORE.md)** - Supported product definition and non-goals +- **[Support Matrix](docs/SUPPORT_MATRIX.md)** - Supported, preview, experimental, and roadmap surfaces +- **[Core Path](docs/CORE_PATH.md)** - Canonical Linux host/peer workflow and checkpoints - **[User Guide](docs/user-guide.md)** - Complete usage instructions, installation steps, and troubleshooting - **[API Reference](docs/api.md)** - Full C API documentation with examples - **[Architecture](docs/architecture.md)** - Technical deep-dive into protocol, security model, and internals @@ -701,9 +704,9 @@ including integration with GitHub Copilot, Claude, and ChatGPT. ## Clients -### KDE Plasma Native Client (Recommended) +### KDE Plasma Client (Preview) -RootStream now features a **native KDE Plasma Qt/QML client** for the best Linux desktop experience: +A separate KDE Plasma Qt/QML client exists in-tree: ```bash cd clients/kde-plasma-client @@ -713,15 +716,13 @@ make -j$(nproc) sudo make install ``` -**Features:** -- Native Qt 6 / QML interface -- KDE Plasma integration -- Hardware-accelerated decoding (VA-API) -- PulseAudio/PipeWire audio support -- AI logging mode for debugging -- Comprehensive settings management +Current status: + +- visible desktop client target with its own build system +- not the canonical supported client path +- subtree README still marks several core runtime areas as in progress -See **[clients/kde-plasma-client/README.md](clients/kde-plasma-client/README.md)** for complete documentation. +See **[clients/kde-plasma-client/README.md](clients/kde-plasma-client/README.md)** for subtree-specific details, and see **[docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md)** before treating it as a supported default. ## Contributing diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e391e18..d559f77 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,5 +1,14 @@ # RootStream Technical Architecture +This document explains subsystem structure and intended technical boundaries. It is not the source of truth for support status, roadmap scope, or current execution progress. + +Use these documents for neighboring questions: + +- Support status: [`docs/SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md) +- Supported product scope: [`docs/PRODUCT_CORE.md`](PRODUCT_CORE.md) +- Current execution work: [`docs/microtasks.md`](microtasks.md) +- Claims evidence: [`docs/audits/claims_audit.md`](audits/claims_audit.md) + ## Design Philosophy RootStream is built on one core principle: **Use the kernel APIs directly**. Every abstraction layer adds latency, complexity, and failure points. We bypass them all. @@ -45,7 +54,7 @@ UDP socket - Uses kernel APIs (stable for 10+ years) - Reduced permission requirements (video group membership) - Reduced compositor dependencies -- Target latency: 14-24ms (varies by hardware; see Performance section) +- Latency targets exist, but benchmark-backed proof belongs in dedicated benchmark and performance docs rather than this architecture summary ## Component Details @@ -104,10 +113,10 @@ munmap(pixels, size); **What is VA-API?** Video Acceleration API - hardware video encoding/decoding interface. -**Supported Hardware:** +**Current acceleration codepaths in tree:** - Intel: All modern integrated + discrete GPUs - AMD: AMDGPU driver (GCN 1.0+) -- NVIDIA: Via VDPAU wrapper (lower performance) +- NVIDIA: NVIDIA-oriented code exists in-tree, but the current public support story is still being reconciled **How It Works:** ```c diff --git a/docs/CORE_PATH.md b/docs/CORE_PATH.md new file mode 100644 index 0000000..7ff77ff --- /dev/null +++ b/docs/CORE_PATH.md @@ -0,0 +1,81 @@ +# RootStream Core Path + +This document describes the single canonical RootStream path the repository currently treats as the supported product journey. It is intentionally narrow and Linux-first. + +The path below is grounded in the current root build, the native CLI entrypoints in [`src/main.c`](../src/main.c), and the existing integration script in [`tests/integration/test_stream.sh`](../tests/integration/test_stream.sh). Where full runtime proof is still incomplete, that limitation is stated explicitly instead of being hidden. + +Use neighboring docs for adjacent truth: + +- Product definition and non-goals: [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md) +- Support and maturity status: [`docs/SUPPORT_MATRIX.md`](./SUPPORT_MATRIX.md) +- Future-only work: [`docs/ROADMAP.md`](./ROADMAP.md) +- Architecture boundaries: [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md) + +## Canonical Scope + +- Host: Linux native `rootstream host` +- Peer: Linux native `rootstream connect ` +- Network model: direct peer-to-peer on a LAN or similarly controlled network +- Pairing/bootstrap: `rootstream --qr`, peer code, and local discovery paths + +This document does not define a KDE-first, mobile-first, browser-first, VR-first, or cloud-managed workflow. + +## Prerequisites + +- Linux environment for both host and peer +- Native RootStream build completed from the root project +- A usable display/capture environment on the host for an actual first stream +- Network reachability between host and peer on the chosen port +- Required root build dependencies available for the selected environment + +## Canonical Sequence + +1. Build the native binary from the repository root. +2. On the future host machine, run `rootstream --qr` once to generate identity material and expose a shareable RootStream code. +3. On the host machine, start the streaming side with `rootstream host`. +4. On the peer Linux machine, connect with `rootstream connect `. +5. Confirm that the peer reaches the first successful encrypted stream state. + +## Validation Checkpoints + +| Step | Command or observation | Expected signal | Failure indicator | Diagnose next | +| --- | --- | --- | --- | --- | +| Binary available | `./rootstream --help` | Usage output renders and exits without crashing | Binary missing or command exits unexpectedly | Re-check the root build path, root `Makefile`, and `CMakeLists.txt`. | +| Identity generation | `XDG_CONFIG_HOME=/tmp/rootstream-core ./rootstream --qr` | Output includes `RootStream Code:` and a code containing `@`; integration script also expects generated keys under `$XDG_CONFIG_HOME/rootstream/keys/` | No code output, missing key files, or crypto/init failure | Inspect [`src/main.c`](../src/main.c), [`src/qrcode.c`](../src/qrcode.c), and the key-generation checks in [`tests/integration/test_stream.sh`](../tests/integration/test_stream.sh). | +| Host startup | `./rootstream host --port 19876` | CLI prints `INFO: Starting host mode`, selects or falls back to a display, then prints `✓ All systems ready` and `→ Waiting for connections...` | Immediate exit, `ERROR: Network init failed`, or display-selection failure | Inspect host stdout/stderr first, then host-side dependency and display assumptions in [`docs/SUPPORT_MATRIX.md`](./SUPPORT_MATRIX.md). | +| Peer initiation | `./rootstream connect ` | CLI prints `INFO: Connecting to peer: ...`, then `✓ Connection initiated` and `INFO: Waiting for handshake...` | `ERROR: Failed to connect to peer` or early exit from the client path | Inspect peer connectivity, the supplied code, and the connect path in [`src/main.c`](../src/main.c). | +| First-stream attempt | Host remains alive while the peer enters the client service loop | Host and peer both stay running long enough to indicate the session path advanced beyond argument parsing and initial network setup | Client or host exits immediately after connect, or no session progress is visible | Use host and peer logs first; then compare behavior with the loopback checks in [`tests/integration/test_stream.sh`](../tests/integration/test_stream.sh). | + +## Automation Reference + +- [`tests/integration/test_stream.sh`](../tests/integration/test_stream.sh) currently validates adjacent pieces of the canonical path: + - CLI startup + - key generation + - QR output + - host startup and network binding + - config creation + - loopback setup when a display is available +- The script does not yet prove a full sustained interactive client render path. That remains follow-up work in Phase 99. + +## Why This Is the Canonical Path + +- It maps directly to the root executable and command surface already present in [`src/main.c`](../src/main.c). +- It aligns with the product scope in [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md). +- It avoids treating the KDE client, web dashboard, Windows client, or mobile apps as equally supported defaults. +- The repository’s integration script already exercises adjacent pieces of this path: help/version startup, identity generation, QR output, host startup, config handling, and loopback setup. + +## Current Limitations + +- The repository has stronger evidence for startup, identity generation, QR output, and host/network initialization than it does for a fully validated end-to-end first-frame client success path. +- The integration script currently stops short of proving a complete interactive client session; it verifies loopback setup rather than a full sustained client render path. +- Hardware acceleration, mDNS convenience, GUI mode, and recording depend on optional system packages and runtime conditions. +- This path should currently be read as the canonical supported journey to optimize and validate further, not as proof that every adjacent surface has equal maturity. + +## Adjacent Paths That Are Not Canonical + +- `rootstream-kde-client` +- `rootstream-client` on Windows +- React dashboard and optional web API surfaces +- Android and iOS clients +- VR / Proton surfaces +- Infrastructure or cloud deployment surfaces diff --git a/docs/IMPLEMENTATION_STATUS.md b/docs/IMPLEMENTATION_STATUS.md index 031f135..6424a2d 100644 --- a/docs/IMPLEMENTATION_STATUS.md +++ b/docs/IMPLEMENTATION_STATUS.md @@ -2,38 +2,31 @@ ## 🎯 Overview -This document details what is **actually implemented** vs. what is **claimed** in the README and issues. - -> **Single source of truth for microtasks:** [`docs/microtasks.md`](microtasks.md) - -**Last Updated:** 2026 (Post-Phase 31 · Vulkan Renderer Complete)** - -### 📊 High-Level Phase Completion - -| Range | Phases | Status | -|-------|--------|--------| -| Core Infrastructure | 0–8 | ✅ Complete | -| Protocol & Crypto | 9–11 | ✅ Complete | -| KDE Client | 12–16 | ✅ Complete | -| Platform & Recording | 17–19 | ✅ Complete | -| Advanced Features | 20–23 | ✅ Complete | -| VR / Proton | 24 | 🔄 In Progress (5/9 tasks) | -| Security Hardening | 25 | ✅ Complete | -| Network Optimization | 26 | ✅ Complete | -| CI / Infrastructure | 27 | ✅ Complete | -| Event Sourcing | 28 | ✅ Complete | -| Mobile Full Client | 29 | 🔄 In Progress (3/8 tasks) | -| Security Phase 2 | 30 | ✅ Complete | -| Vulkan Renderer | 31 | ✅ Complete | -| Backend Integration | 32 | 🔴 Not Started | -| Code Standards | 33 | 🔴 Not Started | -| Production Readiness | 34 | 🔴 Not Started | - -**Overall: 186 / 221 microtasks complete (84%)** +This document now serves as a legacy implementation-notes companion, not as the canonical support or execution-status source. + +Use these documents for current truth: + +- Current execution status and active work: [`docs/microtasks.md`](microtasks.md) +- Supported product definition: [`docs/PRODUCT_CORE.md`](PRODUCT_CORE.md) +- Supported, preview, experimental, and roadmap surfaces: [`docs/SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md) +- Claims evidence and mismatches: [`docs/audits/claims_audit.md`](audits/claims_audit.md) + +**Last Updated:** 2026-03-12 + +### 📊 Current Truth Boundary + +| Topic | Current source of truth | Current read | +|-------|--------------------------|--------------| +| Execution ledger | [`docs/microtasks.md`](microtasks.md) | Canonical execution tracking resumes at Phase 98. | +| Supported product path | [`docs/PRODUCT_CORE.md`](PRODUCT_CORE.md) | Linux host plus Linux peer is the current supported core. | +| Support and maturity labels | [`docs/SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md) | Only the Linux native root path is currently supported; KDE/Windows are preview; web/mobile/VR are not supported defaults. | +| Claim grading | [`docs/audits/claims_audit.md`](audits/claims_audit.md) | README, status, and subsystem claims are graded as evidenced, partial, unsupported, or unclear. | + +Historical phase notes remain below as legacy implementation context. They should not be read as the current support matrix, roadmap, or execution ledger. --- -## ✅ Fully Implemented (Phases 0-7) +## Historical Phase Notes (Legacy) ### PHASE 0: Backend Infrastructure - [x] Context struct with backend tracking diff --git a/docs/PRODUCT_CORE.md b/docs/PRODUCT_CORE.md new file mode 100644 index 0000000..e2780a9 --- /dev/null +++ b/docs/PRODUCT_CORE.md @@ -0,0 +1,119 @@ +# RootStream Product Core + +This document defines the supported RootStream product based on repository evidence gathered in Phase 98.1. It is not a roadmap. It describes the product path the repository can currently defend with code, build targets, and visible entrypoints. + +For neighboring questions: + +- Support and maturity labels: [`docs/SUPPORT_MATRIX.md`](./SUPPORT_MATRIX.md) +- Step-by-step supported workflow: [`docs/CORE_PATH.md`](./CORE_PATH.md) +- Future work only: [`docs/ROADMAP.md`](./ROADMAP.md) +- Architecture and subsystem boundaries: [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md) + +## Purpose + +RootStream is a Linux-first, self-hosted, peer-to-peer game streaming toolchain for people who want direct device-to-device streaming without accounts or a required cloud control-plane. + +The product core today is deliberately narrower than the full repository surface. The repo contains KDE, web, mobile, VR, and infrastructure code, but those surfaces are not the primary supported product path until later phases establish support, build, and runtime proof for them. + +## Supported Product Today + +The current supported product definition is: + +- Host a stream from a Linux machine using the native `rootstream` executable. +- Connect from another Linux machine using the native `rootstream connect ` path exposed by `src/main.c`. +- Run this as a direct peer-to-peer workflow on a local network or equivalent private network where the host and client can reach each other. +- Use the project's built-in pairing, discovery, encryption, capture, encode, and transport layers that are already represented in the root build and native runtime. + +This definition is evidence-backed by: + +- The root build and entrypoints in [`CMakeLists.txt`](../CMakeLists.txt) and [`src/main.c`](../src/main.c). +- The repository inventory in [`docs/audits/repository_inventory.md`](./audits/repository_inventory.md). +- The claims grading in [`docs/audits/claims_audit.md`](./audits/claims_audit.md). +- The contradiction mapping in [`docs/audits/truth_source_conflicts.md`](./audits/truth_source_conflicts.md). + +## Primary User and Use Case + +The primary supported user is a technical Linux user who wants to stream games or an interactive Linux desktop session directly to a peer device without depending on hosted accounts or a vendor cloud. + +The primary supported use case is: + +- start the Linux host with `rootstream host` +- pair or connect directly with a peer +- join from another Linux machine with `rootstream connect ` +- complete a first encrypted stream on a LAN or similarly controlled network + +This is the path the repository should optimize, document, test, and truthfully present first. + +## Supported User Journey + +The supported user journey today is: + +1. Build or install the native Linux `rootstream` executable in a Linux environment. +2. On the host machine, start the streaming side with `rootstream host`. +3. Use `rootstream --qr` or the text peer code flow to share host identity material with the peer. +4. On the peer Linux machine, connect with `rootstream connect `. +5. Validate that the session reaches an encrypted first-stream state on a LAN or similarly controlled network. + +This journey is intentionally narrow. It maps to command surfaces and entrypoints already exposed by [`src/main.c`](../src/main.c) rather than to the broader collection of in-tree clients and dashboards. + +## Canonical Product Path + +Until support and runtime validation work says otherwise, the canonical product path is: + +1. Linux host via `rootstream host` +2. Linux peer via `rootstream connect ` +3. direct P2P networking, local discovery, and built-in encryption + +The KDE client, web dashboard, mobile apps, VR stack, Windows client packaging story, and infrastructure surfaces remain outside this canonical path for now. Some of them contain substantial code, but current repository evidence does not justify presenting them as the default supported product. + +## Target Platforms + +Supported target platform for the product core: + +- Linux host +- Linux-focused native runtime and tooling +- private LAN or similarly controlled network environment + +Present in the repository but not part of the supported core today: + +- KDE Plasma desktop client subtree +- Windows client executable path +- Android client +- iOS client +- React web dashboard +- VR / Proton surfaces +- cloud and infrastructure deployment surfaces + +## Non-Goals for the Current Product Definition + +These are explicit non-goals for the currently supported product path: + +- treating the KDE Plasma client as the default supported desktop client +- treating Android or iOS as first-class supported client paths +- treating the React dashboard as a default operations or control surface +- treating VR / Proton work as part of the supported baseline experience +- treating cloud deployment, hosted control planes, or account systems as part of the product core +- treating benchmark targets or roadmap ambitions as present support claims +- treating "code exists in-tree" as equivalent to "supported and validated" + +These non-goals may change in later phases, but they are excluded from the current support definition until the repository has support-matrix, runtime, and validation proof to back them. + +## Explicit Exclusions From the Product Core + +The following are excluded from the current product core definition even when code exists in-tree: + +- cloud-managed or centrally hosted RootStream service offerings +- browser-first or WebRTC-first client support +- mobile clients as a default supported path +- KDE client as the primary recommended desktop client +- VR / OpenXR support as part of the default product claim +- benchmark-backed performance claims beyond the evidence currently captured in the repo + +These exclusions are based on the current audit evidence, not on long-term desirability. + +## Document Role + +- This document defines what RootStream is and which path the repository currently supports. +- `docs/SUPPORT_MATRIX.md` will later classify adjacent surfaces by maturity. +- `docs/CORE_PATH.md` will later describe the single step-by-step supported journey. +- `README.md` should eventually summarize this document instead of competing with it. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d80a6b5..3c0a1c8 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,7 +1,9 @@ # RootStream Roadmap -This roadmap is **not a contract**, but a guide. -RootStream will evolve as we learn from real-world usage, hardware quirks, and community feedback. +This roadmap is **not a contract** and it is not the source of truth for current support. +Use [`docs/PRODUCT_CORE.md`](PRODUCT_CORE.md) for the supported product definition, [`docs/SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md) for current surface maturity, and [`docs/microtasks.md`](microtasks.md) for active execution work. + +This document should describe future work, hardening targets, and deferred ambitions only. Core principles (these NEVER change): @@ -13,13 +15,13 @@ Core principles (these NEVER change): --- -## v1.1 – Core Loop & Client MVP +## v1.1 – Linux Core Path Hardening Goal: **End-to-end Linux ↔ Linux streaming that is boringly reliable.** ### Features -- [ ] Linux client MVP +- [ ] Harden the existing Linux peer/client path - [ ] VA-API decode path - [ ] Basic frame presentation (SDL2 or DRM/KMS) - [ ] Input capture + injection (keyboard/mouse) @@ -109,7 +111,7 @@ Goal: **Turn RootStream into a clean reference implementation and protocol that - [ ] `rootstream host --headless --card /dev/dri/cardX` - [ ] Use cases: render nodes, CI visualizations, remote GPU workloads -- [ ] Windows client (client-only, no host) +- [ ] Harden the existing Windows client path into a supportable client-only lane - [ ] Decode + input only - [ ] LAN/VPN use, no cloud diff --git a/docs/SUPPORT_MATRIX.md b/docs/SUPPORT_MATRIX.md new file mode 100644 index 0000000..08a4597 --- /dev/null +++ b/docs/SUPPORT_MATRIX.md @@ -0,0 +1,94 @@ +# RootStream Support Matrix + +This matrix records the current support posture of visible RootStream surfaces based on repository evidence gathered in Phase 98.1 and refined by the product-core definition in [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md). + +This document answers a narrower question than "does code exist?" It records what the repository currently supports, what appears usable but not yet support-committed, what remains experimental, and what should be treated as roadmap-only or non-core until stronger proof exists. + +Use neighboring docs for different questions: + +- Product definition and non-goals: [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md) +- Canonical supported workflow: [`docs/CORE_PATH.md`](./CORE_PATH.md) +- Future-only work: [`docs/ROADMAP.md`](./ROADMAP.md) +- Architecture boundaries: [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md) + +## Maturity Categories + +| Status | Meaning | +| --- | --- | +| Supported | Present in the repository, part of the current product core, and something the docs should actively direct users toward today. | +| Preview | Present and intentionally visible, but not yet the canonical supported path; may have partial validation or incomplete support commitments. | +| Experimental | Code exists, but implementation presence is not the same as support; build, runtime, or documentation proof is incomplete, ambiguous, or contradicted elsewhere. | +| Roadmap | Future-facing work or a target state that should not be described as current support, even if adjacent scaffolding or partial code exists. | + +These labels describe support commitment, not just code presence. A surface can exist in-tree and still be `Experimental` or `Roadmap` if the repository does not currently provide enough evidence to support it honestly. + +## Surface Matrix + +| Surface | Role | Status | Primary evidence | Evidence basis | +| --- | --- | --- | --- | --- | +| Linux native host via `rootstream host` | Core host path | Supported | [`src/main.c`](../src/main.c), [`CMakeLists.txt`](../CMakeLists.txt), [`tests/integration/test_stream.sh`](../tests/integration/test_stream.sh) | Root build exposes the Linux host executable and CI builds/tests the native path on Ubuntu. | +| Linux native peer via `rootstream connect ` | Core peer path | Supported | [`src/main.c`](../src/main.c), [`src/service.c`](../src/service.c), [`src/client_session.c`](../src/client_session.c) | The shared native runtime exposes a Linux peer connection flow in the main executable and the product core defines this as the canonical peer path. | +| Linux pairing and discovery (`--qr`, peer code, mDNS/broadcast/manual`) | Core connection bootstrap | Supported | [`src/qrcode.c`](../src/qrcode.c), [`src/discovery.c`](../src/discovery.c), [`src/discovery_broadcast.c`](../src/discovery_broadcast.c), [`src/discovery_manual.c`](../src/discovery_manual.c) | Pairing and discovery code exists in the root runtime and is already part of the native Linux flow. | +| KDE Plasma client subtree | Alternate Linux desktop client | Preview | [`clients/kde-plasma-client/CMakeLists.txt`](../clients/kde-plasma-client/CMakeLists.txt), [`clients/kde-plasma-client/README.md`](../clients/kde-plasma-client/README.md) | A separate Qt/KDE client target exists, but its own README still marks core runtime areas as in progress, so it is not the canonical supported client. | +| Windows `rootstream-client` | Windows peer/client executable | Preview | [`src/main_client.c`](../src/main_client.c), [`CMakeLists.txt`](../CMakeLists.txt), [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) | A Windows client entrypoint and CI build job exist, but the roadmap and top-level product positioning do not yet present it as part of the supported core. | +| Embedded web API backend in `src/web/` | Optional management/backend surface | Experimental | [`src/web/api_server.c`](../src/web/api_server.c), [`src/web/websocket_server.c`](../src/web/websocket_server.c), [`CMakeLists.txt`](../CMakeLists.txt) | Backend code exists behind the optional `BUILD_WEB_DASHBOARD` flag, but the default root build and supported run path do not currently make it a primary supported surface. | +| React web dashboard in `frontend/` | Browser management UI | Experimental | [`frontend/package.json`](../frontend/package.json), [`frontend/README.md`](../frontend/README.md) | The frontend is present, but its backend/API assumptions are not yet tied to a verified supported top-level entrypoint. | +| Android client in `android/RootStream/` | Mobile peer/client app | Experimental | [`android/README.md`](../android/README.md), [`android/RootStream/app/build.gradle.kts`](../android/RootStream/app/build.gradle.kts) | The Android app structure is substantial, but its own implementation-status section still marks rendering, decode, audio, network, and discovery as stub or TODO. | +| iOS client in `ios/RootStream/` | Mobile peer/client app | Experimental | [`ios/RootStream/README.md`](../ios/RootStream/README.md), [`ios/RootStream/RootStream/App/RootStreamApp.swift`](../ios/RootStream/RootStream/App/RootStreamApp.swift) | The app, workspace, and CI exist, but the repository still lacks a validated supported product path for iOS. | +| VR / Proton stack in `src/vr/` | Immersive/adjacent runtime surface | Experimental | [`src/vr/README.md`](../src/vr/README.md), [`CMakeLists.txt`](../CMakeLists.txt) | VR code exists behind the optional `BUILD_VR_SUPPORT` path, but current docs and audits do not support treating it as a supported product surface. | +| Cloud, Terraform, Docker, and K8s infrastructure in `infrastructure/` | Operational or deployment assets | Experimental | [`infrastructure/README.md`](../infrastructure/README.md), [`docs/ROADMAP.md`](./ROADMAP.md), [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md) | Infrastructure assets exist, but the supported product core explicitly excludes a cloud-managed or central-control-plane story. | +| Direct NVIDIA-first host acceleration story | High-visibility host capability claim | Roadmap | [`docs/ROADMAP.md`](./ROADMAP.md), [`docs/audits/claims_audit.md`](./audits/claims_audit.md), [`src/nvenc_encoder.c`](../src/nvenc_encoder.c) | NVIDIA-related code exists, but the docs conflict and the repository does not yet provide a clean, supportable NVIDIA-first story for the product core. | +| Full OpenXR-grade VR runtime support | High-visibility adjacent capability claim | Roadmap | [`src/vr/README.md`](../src/vr/README.md), [`docs/audits/claims_audit.md`](./audits/claims_audit.md) | VR scaffolding exists, but the current repo does not support describing full OpenXR headset support as present product reality. | + +## Applied Maturity Labels + +| Visible command, feature, or surface | Current maturity | Notes | +| --- | --- | --- | +| `rootstream host` | Supported | Canonical Linux host entrypoint for the supported product core. | +| `rootstream connect ` | Supported | Canonical Linux peer entrypoint for the supported product core. | +| `rootstream --qr` and peer-code bootstrap | Supported | Part of the current supported pairing and discovery path. | +| `rootstream --record` and native recording path | Preview | Code and CLI exposure exist, but the recording lane is not yet the primary supported story and still needs stronger end-to-end validation. | +| `rootstream-kde-client` | Preview | Visible desktop client target exists, but the subtree still documents several core areas as in progress. | +| `rootstream-client` on Windows | Preview | Build target and CI job exist, but the product core remains Linux-first and does not yet treat Windows as a default supported path. | +| Embedded web API/backend plus React dashboard | Experimental | Present and visible, but the supported build/run path remains ambiguous. | +| Android client | Experimental | Significant app structure exists, but core runtime areas remain stubbed or incomplete in the subtree's own status language. | +| iOS client | Experimental | App and CI surfaces exist, but the supported path is still unvalidated. | +| VR / Proton code path | Experimental | In-tree code exists, but the repo does not currently support presenting it as a stable user-facing product lane. | +| Direct NVIDIA-first host path | Roadmap | README and roadmap language still disagree about what is truly available today. | +| Full OpenXR-grade VR path | Roadmap | The future target should remain future language until later phases prove otherwise. | + +## Support Direction + +- The only currently supported end-user product path is the Linux native host and Linux native peer flow documented in [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md). +- Preview surfaces may become supported later, but they should not be presented as default or equally validated today. +- Experimental surfaces should be documented honestly as present code, not as support commitments. +- Future support expansion should only happen after build, runtime, and documentation proof exists for the target surface. + +## Environment Constraints and Caveats + +| Surface | Current environment assumptions | Caveats and unsupported or unverified environments | +| --- | --- | --- | +| Linux native host via `rootstream host` | Linux build using the root CMake/Make flow; core dependencies include SDL2, libsodium, Opus, libdrm, ALSA, and on non-headless builds GTK3; CI currently exercises Ubuntu Linux in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml). | This is the only supported product surface. Hardware acceleration, discovery, GUI mode, and recording vary with optional dependencies such as VA-API, Avahi, PulseAudio, PipeWire, FFmpeg, X11, and ncurses. Browser-only, cloud-managed, and non-Linux host paths are outside the supported core. | +| Linux native peer via `rootstream connect ` | Same Linux native toolchain and shared runtime as the host path; peer flow is exposed by [`src/main.c`](../src/main.c) and depends on the root build succeeding. | This path is supported only as part of the Linux-to-Linux native core definition. A broader multi-platform client support promise is not yet justified. | +| Linux pairing and discovery (`--qr`, peer code, mDNS/broadcast/manual`) | QR generation depends on the root native runtime; mDNS depends on Avahi when available; fallback discovery code exists for broadcast and manual entry. | Discovery convenience depends on optional packages and local-network conditions. The repository supports the existence of these paths, but not a universal "zero configuration" promise across all environments. | +| KDE Plasma client subtree | Linux desktop environment with Qt 6.4+, libsodium, Opus, and `libRootStream`; optional KDE Frameworks 6, VA-API, PulseAudio, and PipeWire per [`clients/kde-plasma-client/README.md`](../clients/kde-plasma-client/README.md). | The subtree README still marks video rendering, audio playback, input injection, metrics, and mDNS as in progress. It should be treated as preview rather than as the default supported client. | +| Windows `rootstream-client` | Windows build path exists in CMake and CI. | Current product-core docs do not treat Windows as part of the supported core, and no canonical Windows-first journey is documented yet. | +| Embedded web API backend in `src/web/` | Requires opting into `BUILD_WEB_DASHBOARD=ON` in [`CMakeLists.txt`](../CMakeLists.txt). | Not part of the default root build or the current supported product path. Runtime and packaging expectations remain ambiguous. | +| React web dashboard in `frontend/` | Requires Node.js 16+ and npm; expects backend services on `localhost:8080` and `localhost:8081` per [`frontend/README.md`](../frontend/README.md). | Browser UI should be treated as experimental until a supported backend run path and environment story are documented and validated. | +| Android client in `android/RootStream/` | Android Studio Hedgehog or later, JDK 17, Android SDK 34, NDK r25c+, Gradle 8.2+, and Android API 24+ per [`android/README.md`](../android/README.md). | The Android subtree documents major rendering, decode, audio, network, discovery, and PiP work as stub or TODO. It is unverified as a supported client path. | +| iOS client in `ios/RootStream/` | iOS 15+, Xcode 14+, CocoaPods, and a Metal-capable device per [`ios/RootStream/README.md`](../ios/RootStream/README.md). | The iOS subtree is present, but the repository does not yet provide a validated, support-committed iOS user journey. | +| VR / Proton stack in `src/vr/` | Requires opting into `BUILD_VR_SUPPORT=ON`; README assumes VR hardware and platform-specific runtimes. | The VR README itself says the current implementation is stub/mock and that fuller OpenXR integration remains future work. | +| Cloud, Terraform, Docker, and K8s infrastructure in `infrastructure/` | Requires separate Docker, Terraform, Kubernetes, and cloud tooling outside the root product build. | These assets exist, but the product core explicitly excludes a required cloud control-plane or hosted service story. They should not be read as proof of supported cloud deployment for end users. | + +## Current Support Boundary + +- Supported today means Linux-first native host and Linux-first native peer on a private or similarly controlled network. +- Preview and experimental surfaces may build or contain substantial code, but they are not equivalent to a documented and validated support commitment. +- Environments not explicitly named above should be treated as unverified until later phases produce concrete build, runtime, and troubleshooting evidence. + +## Source Links + +- Product scope: [`docs/PRODUCT_CORE.md`](./PRODUCT_CORE.md) +- Repository inventory: [`docs/audits/repository_inventory.md`](./audits/repository_inventory.md) +- Claims grading: [`docs/audits/claims_audit.md`](./audits/claims_audit.md) +- Conflict map: [`docs/audits/truth_source_conflicts.md`](./audits/truth_source_conflicts.md) diff --git a/docs/audits/claims_audit.md b/docs/audits/claims_audit.md new file mode 100644 index 0000000..9d55a22 --- /dev/null +++ b/docs/audits/claims_audit.md @@ -0,0 +1,44 @@ +# RootStream Claims Audit + +This audit compares high-visibility product claims against repository evidence visible on disk on 2026-03-12. Labels are: + +- `EVIDENCED`: code, manifests, tests, or build targets directly support the claim. +- `PARTIAL`: some implementation exists, but the claim overstates completeness, support, or validation. +- `UNSUPPORTED`: the claim conflicts with current repository evidence or names a capability not supported by the visible implementation. +- `UNCLEAR`: the claim may be plausible, but the repository does not currently provide enough evidence to treat it as proved. + +## Audited Claims + +| Source | Claim | Repository evidence | Label | Follow-up | +| --- | --- | --- | --- | --- | +| [`README.md`](../../README.md) | RootStream is a Linux-oriented secure P2P streaming product. | Root [`CMakeLists.txt`](../../CMakeLists.txt) builds the Linux `rootstream` executable; [`src/main.c`](../../src/main.c), [`src/network.c`](../../src/network.c), and [`src/crypto.c`](../../src/crypto.c) provide host/network/crypto paths. | `EVIDENCED` | `98.2.1` | +| [`README.md`](../../README.md) | "Zero-configuration" pairing via QR code and instant connection. | [`src/qrcode.c`](../../src/qrcode.c), [`src/main.c`](../../src/main.c), and integration script [`tests/integration/test_stream.sh`](../../tests/integration/test_stream.sh) show QR generation and peer-code flow; however, there is no completed golden-path validation proving a frictionless first-run experience. | `PARTIAL` | `98.4.1`, `99.3.2`, `99.6.2` | +| [`README.md`](../../README.md) | VA-API hardware encoding is available on Intel/AMD. | [`CMakeLists.txt`](../../CMakeLists.txt) detects VA-API and compiles [`src/vaapi_encoder.c`](../../src/vaapi_encoder.c); [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md) and tests reference the VA-API path. | `EVIDENCED` | `98.3.1` | +| [`README.md`](../../README.md) | NVIDIA support is via a VDPAU wrapper and consumer GPU support is "Yes". | The repo contains [`src/nvenc_encoder.c`](../../src/nvenc_encoder.c) and `HAVE_NVENC` checks, but no VDPAU wrapper source was found. [`docs/ROADMAP.md`](../../docs/ROADMAP.md) still lists direct NVENC support as future work. | `UNSUPPORTED` | `98.6.1`, `98.7.1`, `99.1.1` | +| [`README.md`](../../README.md), [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) | End-to-end latency is around `14-24ms` and baseline memory is around `15MB`. | The repo has component benchmarks in [`benchmarks/`](../../benchmarks) and host-side latency logging, but no current baseline report or reproducible end-to-end measurement artifact was found. README itself later says the numbers come from limited testing and no comprehensive benchmark suite exists yet. | `UNCLEAR` | `104.1.1`, `104.3.1`, `104.5.1` | +| [`README.md`](../../README.md) | mDNS discovery and LAN auto-discovery are implemented. | [`src/discovery.c`](../../src/discovery.c), [`src/discovery_broadcast.c`](../../src/discovery_broadcast.c), [`src/discovery_manual.c`](../../src/discovery_manual.c), `HAVE_AVAHI` checks, and [`tests/integration/test_discovery_fallback.c`](../../tests/integration/test_discovery_fallback.c) support this. | `EVIDENCED` | `98.4.1` | +| [`README.md`](../../README.md) | Recording supports multiple codecs, container formats, smart storage, and instant replay. | [`src/recording/recording_manager.cpp`](../../src/recording/recording_manager.cpp), encoder wrappers, [`src/recording/disk_manager.h`](../../src/recording/disk_manager.h), [`src/recording/replay_buffer.h`](../../src/recording/replay_buffer.h), and recording tests exist; the top-level CLI path visibly exposes only basic `--record FILE` flow and the supported surface is not yet documented. | `PARTIAL` | `98.3.1`, `98.6.1`, `99.5.1` | +| [`README.md`](../../README.md) | The KDE Plasma client is the recommended native desktop client. | [`clients/kde-plasma-client/CMakeLists.txt`](../../clients/kde-plasma-client/CMakeLists.txt) defines `rootstream-kde-client`, but the client README still marks video rendering, audio playback, input injection, performance metrics, and mDNS discovery as in progress. | `PARTIAL` | `98.6.1`, `98.7.1`, `99.3.2` | +| [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md) | KDE client phases 12-16 are complete. | The subtree build and sources are present, but [`clients/kde-plasma-client/README.md`](../../clients/kde-plasma-client/README.md) explicitly lists core areas as still in progress. | `UNSUPPORTED` | `98.7.1` | +| [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md) | The embedded web dashboard API server, WebSocket push, and auth token support are complete. | [`src/web/api_server.c`](../../src/web/api_server.c), [`src/web/websocket_server.c`](../../src/web/websocket_server.c), and [`tests/unit/test_web_dashboard.c`](../../tests/unit/test_web_dashboard.c) exist, but no standalone web-dashboard executable target was found in the current root build graph. | `PARTIAL` | `98.3.1`, `98.7.1`, `99.1.1` | +| [`frontend/README.md`](../../frontend/README.md) | A real-time web dashboard exists for monitoring and management. | [`frontend/package.json`](../../frontend/package.json) and React sources under [`frontend/src/`](../../frontend/src) exist; backend assumptions are documented, but the current supported run/build path is ambiguous and not tied to a verified top-level entrypoint. | `PARTIAL` | `98.3.1`, `99.1.1` | +| [`android/README.md`](../../android/README.md) | The Android client is a native secure P2P streaming application with rendering, decode, discovery, controls, and PiP. | The Gradle app, manifest, `MainActivity`, and JNI scaffolding exist, but the README's own implementation-status section marks Vulkan, OpenGL ES, video decode, audio, network, discovery, and PiP as stubs or TODO. | `PARTIAL` | `98.3.1`, `98.6.2`, `98.7.1` | +| [`ios/RootStream/README.md`](../../ios/RootStream/README.md) | The iOS client provides Metal rendering, VideoToolbox decode, mDNS, and biometric auth. | The iOS app source tree and CI workflow exist; [`ios/RootStream/RootStream/UI/LoginView.swift`](../../ios/RootStream/RootStream/UI/LoginView.swift) and [`ios/RootStream/RootStream/Utils/SecurityManager.swift`](../../ios/RootStream/RootStream/Utils/SecurityManager.swift) show biometric-related code, but the login flow still contains placeholder completion text and no supported product path has been validated. | `PARTIAL` | `98.3.1`, `98.6.2`, `98.7.1` | +| [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md) | VR / Proton support is materially implemented. | VR sources and tests are present, but [`src/vr/README.md`](../../src/vr/README.md) says the current implementation provides stub/mock functionality and full OpenXR integration remains future work. | `PARTIAL` | `98.3.1`, `98.7.1`, `101.6.1` | +| [`infrastructure/README.md`](../../infrastructure/README.md) | RootStream has cloud infrastructure for deployment and management across AWS, Azure, and GCP. | Infrastructure source and Terraform/Docker/K8s files exist, but [`docs/ROADMAP.md`](../../docs/ROADMAP.md) explicitly lists user accounts, central servers, and any cloud control-plane as out of scope. | `UNSUPPORTED` | `98.2.1`, `98.3.1`, `98.7.1`, `101.6.1` | + +## High-Risk Mismatches + +- README marketing still leans on NVIDIA via VDPAU-wrapper language, while the visible code path is NVENC-oriented and the roadmap still treats NVIDIA work as future. +- README positions the KDE client as the recommended desktop path, but the client subtree still documents core runtime features as incomplete. +- `docs/IMPLEMENTATION_STATUS.md` overstates completion for at least the KDE client, web dashboard surface, and VR support relative to the current subtree docs and build reality. +- Mobile subtree READMEs present broad capability sets, but their own status sections and code comments show significant stub or placeholder areas. +- Infrastructure docs present a cloud deployment story that conflicts with the roadmap's explicit "no cloud control-plane" stance. + +## Follow-Up Coverage + +- Support and maturity classification: `98.3.1`, `98.5.2` +- README and public truth cleanup: `98.6.1`, `98.6.2` +- Cross-document reconciliation: `98.7.1` +- Build and entrypoint verification for ambiguous surfaces: `99.1.1` +- Benchmark-backed performance truth: `104.1.1`, `104.3.1`, `104.5.1` diff --git a/docs/audits/repository_inventory.md b/docs/audits/repository_inventory.md new file mode 100644 index 0000000..69c0081 --- /dev/null +++ b/docs/audits/repository_inventory.md @@ -0,0 +1,59 @@ +# RootStream Repository Inventory + +This inventory records the current repository layout and likely product entrypoints based on the tree, build files, app manifests, and high-visibility docs present on disk on 2026-03-12. It is intentionally evidence-based and does not treat README claims as implementation proof. + +## Top-Level Subsystems + +| Path | Apparent role | Evidence | +| --- | --- | --- | +| `src/` | Native C/C++ core, runtime, protocol, capture, encode, audio, networking, discovery, recording, security, web, and VR sources | Root [`CMakeLists.txt`](../../CMakeLists.txt) builds `rootstream_core`, `rootstream`, `rstr-player`, and `rootstream-client` from `src/` and related platform sources. | +| `include/` | Public native API headers | [`include/rootstream.h`](../../include/rootstream.h) and [`include/rootstream_client_session.h`](../../include/rootstream_client_session.h) are exported by the root build. | +| `clients/kde-plasma-client/` | Separate Qt 6 / QML KDE desktop client | [`clients/kde-plasma-client/CMakeLists.txt`](../../clients/kde-plasma-client/CMakeLists.txt) defines `rootstream-kde-client`; subtree contains `qml/`, `src/`, packaging, and tests. | +| `frontend/` | React web dashboard frontend | [`frontend/package.json`](../../frontend/package.json) defines `start`, `build`, and `test`; [`frontend/src/index.js`](../../frontend/src/index.js) and [`frontend/src/App.js`](../../frontend/src/App.js) are the frontend entry files. | +| `android/RootStream/` | Android client app with Kotlin and JNI/native rendering helpers | [`android/RootStream/app/build.gradle.kts`](../../android/RootStream/app/build.gradle.kts) defines the app module; native CMake under `app/src/main/cpp/` builds JNI libraries. | +| `ios/RootStream/` | iOS client app with SwiftUI, CocoaPods, and XCTest | [`ios/RootStream/Podfile`](../../ios/RootStream/Podfile), [`ios/RootStream/RootStream/App/RootStreamApp.swift`](../../ios/RootStream/RootStream/App/RootStreamApp.swift), and [`ios/RootStream/RootStreamTests/RootStreamTests.swift`](../../ios/RootStream/RootStreamTests/RootStreamTests.swift) are present. | +| `infrastructure/` | Cloud, Docker, Kubernetes, monitoring, Terraform, and deploy scripts | Subtrees exist for `cloud/`, `docker/`, `k8s/`, `monitoring/`, `terraform/`, and `scripts/`; see [`infrastructure/README.md`](../../infrastructure/README.md). | +| `benchmarks/` | Standalone performance benchmark sources and instructions | [`benchmarks/README.md`](../../benchmarks/README.md) documents standalone benchmark programs in [`benchmarks/`](../../benchmarks). | +| `tests/` | Root native unit and integration tests | [`tests/CMakeLists.txt`](../../tests/CMakeLists.txt) defines CTest targets for integration and unit coverage. | +| `tools/` | Auxiliary native tools outside the main executable | [`tools/rstr-player.c`](../../tools/rstr-player.c) is built as the `rstr-player` executable by the root CMake project. | +| `scripts/` | Local validation and analysis helpers | Includes [`scripts/smoke.sh`](../../scripts/smoke.sh), [`scripts/run_cppcheck.sh`](../../scripts/run_cppcheck.sh), [`scripts/run_sanitizers.sh`](../../scripts/run_sanitizers.sh), and [`scripts/validate_traceability.sh`](../../scripts/validate_traceability.sh). | +| `packaging/` | Packaging helpers and distro artifacts | Includes [`packaging/build_appimage.sh`](../../packaging/build_appimage.sh) and [`packaging/rootstream.spec`](../../packaging/rootstream.spec). | +| `docs/` | Product, architecture, status, support, troubleshooting, and audit docs | High-visibility docs include [`README.md`](../../README.md), [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md), [`docs/ROADMAP.md`](../../docs/ROADMAP.md), [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md), and [`docs/SECURITY.md`](../../docs/SECURITY.md). | +| `.github/workflows/` | CI surfaces | Current workflows are [`ci.yml`](../../.github/workflows/ci.yml) and [`ios-ci.yml`](../../.github/workflows/ios-ci.yml). | + +## Candidate Product and Developer Entrypoints + +| Surface | Candidate entrypoint | Evidence | Notes | +| --- | --- | --- | --- | +| Linux host / tray app | `rootstream` via [`src/main.c`](../../src/main.c) | Root [`CMakeLists.txt`](../../CMakeLists.txt) defines `add_executable(rootstream src/main.c)` and the file documents default tray, `host`, `connect`, and `--service` modes. | This is the main Linux executable exposed by both CMake and the root [`Makefile`](../../Makefile). | +| Linux recording playback tool | `rstr-player` via [`tools/rstr-player.c`](../../tools/rstr-player.c) | Root [`CMakeLists.txt`](../../CMakeLists.txt) defines `add_executable(rstr-player tools/rstr-player.c)`. | Auxiliary tool, not a primary host/client surface. | +| Windows client | `rootstream-client` via [`src/main_client.c`](../../src/main_client.c) | Root [`CMakeLists.txt`](../../CMakeLists.txt) defines `add_executable(rootstream-client WIN32 src/main_client.c)`. | Windows-only client path. | +| Shared native backend | `rootstream_core` static library | Root [`CMakeLists.txt`](../../CMakeLists.txt) defines `add_library(rootstream_core STATIC ...)`. | Common backend for Linux host/tooling and a likely integration point for other clients. | +| KDE Plasma desktop client | `rootstream-kde-client` via [`clients/kde-plasma-client/src/main.cpp`](../../clients/kde-plasma-client/src/main.cpp) | [`clients/kde-plasma-client/CMakeLists.txt`](../../clients/kde-plasma-client/CMakeLists.txt) defines `add_executable(rootstream-kde-client ...)`. | Separate desktop client subtree with its own packaging and tests. | +| Web dashboard frontend | React app via [`frontend/src/index.js`](../../frontend/src/index.js) | [`frontend/package.json`](../../frontend/package.json) provides `npm start`, `npm run build`, and `npm test`. | Frontend expects REST API on `localhost:8080` and WebSocket on `localhost:8081` per [`frontend/README.md`](../../frontend/README.md). | +| Web dashboard backend/API | Optional `src/web/*.c` sources | Root [`CMakeLists.txt`](../../CMakeLists.txt) appends `src/web/api_server.c`, `websocket_server.c`, `auth_manager.c`, `rate_limiter.c`, and `api_routes.c` when `BUILD_WEB_DASHBOARD=ON`. | A standalone web-dashboard executable was not found in the current top-level target list; this appears to be optional backend functionality folded into the native build. | +| Android app | `com.rootstream.MainActivity` via [`android/RootStream/app/src/main/kotlin/com/rootstream/MainActivity.kt`](../../android/RootStream/app/src/main/kotlin/com/rootstream/MainActivity.kt) | [`android/RootStream/app/build.gradle.kts`](../../android/RootStream/app/build.gradle.kts) defines the `com.rootstream` application module. | Native JNI helpers are built from `app/src/main/cpp/CMakeLists.txt`. | +| Android native helpers | `rootstream_vulkan`, `rootstream_opus`, `rootstream_gles` | [`android/RootStream/app/src/main/cpp/CMakeLists.txt`](../../android/RootStream/app/src/main/cpp/CMakeLists.txt) defines three shared libraries. | These are support libraries, not user-facing launch entrypoints. | +| iOS app | `RootStreamApp` via [`ios/RootStream/RootStream/App/RootStreamApp.swift`](../../ios/RootStream/RootStream/App/RootStreamApp.swift) | [`ios-ci.yml`](../../.github/workflows/ios-ci.yml) builds workspace `RootStream.xcworkspace` and scheme `RootStream`. | iOS subtree contains app, UI, rendering, network, input, and utility sources. | +| Docker/local infra | [`infrastructure/docker/docker-compose.yml`](../../infrastructure/docker/docker-compose.yml) | `docker-compose.yml` is present and documented in [`infrastructure/README.md`](../../infrastructure/README.md). | Infra surface, not part of the default root build. | +| Deployment automation | [`infrastructure/scripts/deploy.sh`](../../infrastructure/scripts/deploy.sh) | Deploy/scale/backup scripts are present under [`infrastructure/scripts/`](../../infrastructure/scripts). | Separate operational path. | +| Terraform infra | [`infrastructure/terraform/main.tf`](../../infrastructure/terraform/main.tf) | Terraform module files are present under [`infrastructure/terraform/`](../../infrastructure/terraform). | Separate operational path. | +| Benchmarks | Standalone sources in [`benchmarks/`](../../benchmarks) | [`benchmarks/encode_latency_bench.c`](../../benchmarks/encode_latency_bench.c), [`benchmarks/network_throughput_bench.c`](../../benchmarks/network_throughput_bench.c), and [`benchmarks/vulkan_renderer_bench.cpp`](../../benchmarks/vulkan_renderer_bench.cpp) are present. | [`benchmarks/README.md`](../../benchmarks/README.md) documents manual invocations; its documented `vulkan_renderer_bench` CMake target was not surfaced by the initial root build-file search. | +| Root native tests | CTest plus standalone test executables | [`tests/CMakeLists.txt`](../../tests/CMakeLists.txt) defines multiple unit and integration test executables. | Separate validation surface. | + +## High-Visibility Documentation Surfaces + +- [`README.md`](../../README.md): public project positioning and install/use claims. +- [`docs/IMPLEMENTATION_STATUS.md`](../../docs/IMPLEMENTATION_STATUS.md): implementation-vs-claim status narrative. +- [`docs/ROADMAP.md`](../../docs/ROADMAP.md): planned or aspirational work. +- [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md): subsystem and design narrative. +- [`docs/SECURITY.md`](../../docs/SECURITY.md): security posture and reporting guidance. +- [`docs/QUICKSTART.md`](../../docs/QUICKSTART.md) and [`docs/TROUBLESHOOTING.md`](../../docs/TROUBLESHOOTING.md): user and contributor onboarding surfaces. + +## First-Pass Boundary Notes + +- The native root build is centered on a shared `rootstream_core` static library and thin executable entrypoints, which means multiple product surfaces depend on the same backend code. +- Desktop client work is split between the root native executable path and the separate KDE/Qt client subtree. +- Web support is split between a React frontend in `frontend/` and optional backend/API sources under `src/web/`. +- Mobile surfaces use separate toolchains and project structures rather than participating in the default root `make` flow. +- Infrastructure, benchmarks, and packaging are all present as separate operational surfaces that should not automatically be treated as supported end-user product paths. diff --git a/docs/audits/truth_source_conflicts.md b/docs/audits/truth_source_conflicts.md new file mode 100644 index 0000000..95023bf --- /dev/null +++ b/docs/audits/truth_source_conflicts.md @@ -0,0 +1,36 @@ +# RootStream Truth-Source Conflict Map + +This document records where repository documents currently disagree about product maturity, support status, or implementation state. It also proposes which document should answer each class of question once reconciliation work is complete. + +## Proposed Truth-Source Boundaries + +| Topic | Proposed primary truth source | Why | +| --- | --- | --- | +| Current execution state and active work queue | [`docs/microtasks.md`](../microtasks.md) | The canonical ledger now owns current-phase task status. | +| Current implementation evidence and claim grading | [`docs/audits/claims_audit.md`](./claims_audit.md) | It explicitly labels visible claims as evidenced, partial, unsupported, or unclear. | +| Repository layout and entrypoints | [`docs/audits/repository_inventory.md`](./repository_inventory.md) | It maps the current tree and build/manifests without marketing language. | +| Future work and aspiration only | [`docs/ROADMAP.md`](../ROADMAP.md) | Roadmap items should describe future intent, not present support. | +| Supported surfaces and maturity levels | `docs/SUPPORT_MATRIX.md` (to be created by `98.3.1`) | Support decisions need a dedicated source instead of being inferred from README prose. | +| Public product positioning | [`README.md`](../../README.md) after `98.6.1` | README should mirror the support matrix and core path instead of inventing parallel truth. | +| Architecture and dependency boundaries | [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md) after `98.7.1` | Architecture should explain structure and constraints, not product support commitments. | + +## Concrete Contradictions + +| Topic | Source A | Source B | Conflict | Proposed truth source | Follow-up | +| --- | --- | --- | --- | --- | --- | +| Current execution status | [`docs/microtasks.md`](../microtasks.md) says the phase-98 ledger is canonical. | [`docs/IMPLEMENTATION_STATUS.md`](../IMPLEMENTATION_STATUS.md) still reports old phase counts and overall completion math. | The repository still contains two incompatible stories about what the current execution program is tracking. | [`docs/microtasks.md`](../microtasks.md) | `98.7.1` | +| Supported platform scope | [`README.md`](../../README.md) says Linux-to-Linux is the supported practical path and recommends other platforms use something else for now. | [`android/README.md`](../../android/README.md) and [`ios/RootStream/README.md`](../../ios/RootStream/README.md) present broad mobile client capability sets. | Top-level positioning narrows support while mobile subtree docs read like active product surfaces. | `docs/SUPPORT_MATRIX.md` | `98.2.1`, `98.3.1`, `98.6.2`, `98.7.1` | +| KDE client readiness | [`README.md`](../../README.md) presents the KDE Plasma client as the recommended native desktop client. | [`clients/kde-plasma-client/README.md`](../../clients/kde-plasma-client/README.md) marks video rendering, audio playback, input injection, metrics, and mDNS as in progress; [`docs/IMPLEMENTATION_STATUS.md`](../IMPLEMENTATION_STATUS.md) calls the KDE phases complete. | High-visibility docs simultaneously present the KDE client as recommended, complete, and still missing core runtime work. | [`docs/audits/claims_audit.md`](./claims_audit.md) until `docs/SUPPORT_MATRIX.md` exists | `98.3.1`, `98.6.1`, `98.7.1` | +| NVIDIA support story | [`README.md`](../../README.md) says NVIDIA works via a VDPAU wrapper and presents consumer GPU support positively. | [`docs/ROADMAP.md`](../ROADMAP.md) says direct NVENC support is future work, while the visible code path is [`src/nvenc_encoder.c`](../../src/nvenc_encoder.c) and no VDPAU wrapper source was found. | The user-facing NVIDIA story is internally inconsistent across README, roadmap, and code evidence. | [`docs/audits/claims_audit.md`](./claims_audit.md) plus `99.1.1` build audit | `98.6.1`, `98.7.1`, `99.1.1` | +| Web dashboard maturity | [`docs/IMPLEMENTATION_STATUS.md`](../IMPLEMENTATION_STATUS.md) says the embedded HTTP API server, WebSocket push, and auth token support are complete. | [`frontend/README.md`](../../frontend/README.md) presents an operational dashboard, while the root build graph only exposes optional `src/web/*.c` sources and no standalone dashboard target. | The repo describes a complete dashboard surface, but the supported build/run story is still ambiguous. | [`docs/audits/claims_audit.md`](./claims_audit.md) until support/build docs are reconciled | `98.3.1`, `98.7.1`, `99.1.1` | +| Performance proof | [`README.md`](../../README.md) and [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md) present `14-24ms` latency and `~15MB` baseline memory figures. | [`README.md`](../../README.md) later says those numbers come from limited testing and that no comprehensive benchmark suite exists yet; current benchmark docs only cover component-level cases. | Performance numbers appear both as headline guidance and as caveated non-baseline data. | Future benchmark docs produced by `104.2.2`, `104.3.1`, and `104.5.1` | `104.1.1`, `104.3.1`, `104.5.1` | +| VR maturity | [`docs/IMPLEMENTATION_STATUS.md`](../IMPLEMENTATION_STATUS.md) lists several VR/OpenXR tasks as completed. | [`src/vr/README.md`](../../src/vr/README.md) says the current VR implementation is stub/mock and full OpenXR integration remains future work. | Status language overstates readiness relative to the subsystem's own README. | [`docs/audits/claims_audit.md`](./claims_audit.md) until support matrix and architecture docs are reconciled | `98.7.1`, `101.6.1` | +| Cloud / no-server model | [`README.md`](../../README.md) says no central servers are required and positions RootStream as direct P2P. [`docs/ROADMAP.md`](../ROADMAP.md) says cloud control-plane work is out of scope. | [`infrastructure/README.md`](../../infrastructure/README.md) presents multi-cloud deployment and management as an infrastructure surface. | Infrastructure docs read like a supported product lane that conflicts with the top-level no-server and no-cloud positioning. | Product scope docs from `98.2.1` plus `docs/SUPPORT_MATRIX.md` | `98.2.1`, `98.3.1`, `98.7.1`, `101.6.1` | +| Roadmap timing vs current code | [`docs/ROADMAP.md`](../ROADMAP.md) places the Windows client in a future `v2.0` section. | [`CMakeLists.txt`](../../CMakeLists.txt) and [`ci.yml`](../../.github/workflows/ci.yml) already define and build `rootstream-client`. | The roadmap still frames a current codepath as future-only work. | [`docs/audits/repository_inventory.md`](./repository_inventory.md) for current existence; [`docs/ROADMAP.md`](../ROADMAP.md) for future work only | `98.7.1`, `99.1.1` | + +## Reconciliation Direction + +- `README.md` should stop being an independent status source and instead summarize the support matrix and core path. +- `docs/IMPLEMENTATION_STATUS.md` should either become a narrowly scoped implementation-evidence report or be reduced to a pointer to the newer audit/support docs. +- `docs/ROADMAP.md` should speak only about future work and should not double as a support or release-state document. +- Subtree READMEs for KDE, web, mobile, VR, and infrastructure should be explicitly labeled as supported, preview, experimental, or non-core once the support matrix exists. diff --git a/docs/microtasks.md b/docs/microtasks.md index 868811f..f112789 100644 --- a/docs/microtasks.md +++ b/docs/microtasks.md @@ -1420,3 +1420,238 @@ > **Overall**: 465 / 465 microtasks complete (**100%**) *Last updated: 2026 · Post-Phase 97 · Next: Phase 98 (Vulkan zero-copy DMABUF, Android/iOS gap fixes)* + + +> Historical snapshot above reflects the registry state through Phase 97. Active transformation phases 98 through 108 continue below in the same table style. + +--- + +## PHASE-98: Product Core Definition + +| ID | Task | Status | +|------|------|--------| +| 98.1.1 | [Repository audit and baseline truth] Create or normalize `/docs/microtasks.md` and seed initial execution ledger | 🟢 | +| 98.1.2 | [Repository audit and baseline truth] Inventory top-level subsystems and entrypoints | 🟢 | +| 98.1.3 | [Repository audit and baseline truth] Identify implemented vs claimed product capabilities | 🟢 | +| 98.1.4 | [Repository audit and baseline truth] Identify conflicting status and truth-source documents | 🟢 | +| 98.2.1 | [Product scope definition] Draft the product core definition | 🟢 | +| 98.2.2 | [Product scope definition] Define supported user journey and non-goals | 🟢 | +| 98.3.1 | [Support matrix creation] Draft `docs/SUPPORT_MATRIX.md` | 🟢 | +| 98.3.2 | [Support matrix creation] Add explicit support caveats and environment constraints | 🟢 | +| 98.4.1 | [Golden path documentation] Draft `docs/CORE_PATH.md` | 🟢 | +| 98.4.2 | [Golden path documentation] Add concrete setup and validation checkpoints to the golden path | 🟢 | +| 98.5.1 | [Feature flag and maturity classification] Define supported, preview, experimental, and roadmap categories | 🟢 | +| 98.5.2 | [Feature flag and maturity classification] Classify visible features and entrypoints by maturity | 🟢 | +| 98.6.1 | [Root README trust cleanup] Revise `README.md` to reflect the supported product honestly | 🟢 | +| 98.6.2 | [Root README trust cleanup] Add explicit not-yet-supported and non-goal language to high-visibility docs | 🟢 | +| 98.7.1 | [Status document reconciliation] Reconcile `IMPLEMENTATION_STATUS`, `ROADMAP`, `ARCHITECTURE`, and audit docs | 🟢 | +| 98.7.2 | [Status document reconciliation] Add status ownership notes to core product docs | 🟢 | + +> Phase 98 progress: 16 / 16 + +--- + +## PHASE-99: Golden Path Hardening + +| ID | Task | Status | +|------|------|--------| +| 99.1.1 | [Build system baseline validation] Audit current build instructions and entrypoints against repository reality | 🔴 | +| 99.1.2 | [Build system baseline validation] Verify the canonical build path from a clean working tree | 🔴 | +| 99.1.3 | [Build system baseline validation] Record build blockers, warnings, and doc gaps | 🔴 | +| 99.2.1 | [Dependency normalization] Separate required dependencies from optional or experimental ones | 🔴 | +| 99.2.2 | [Dependency normalization] Create or refine a reproducible developer bootstrap path | 🔴 | +| 99.3.1 | [Golden path runtime validation] Validate the canonical host path | 🔴 | +| 99.3.2 | [Golden path runtime validation] Validate the canonical client path and first connection flow | 🔴 | +| 99.4.1 | [Error handling and failure-path cleanup] Audit golden-path failure modes and error messages | 🔴 | +| 99.4.2 | [Error handling and failure-path cleanup] Improve first-failure diagnostics in the canonical path | 🔴 | +| 99.5.1 | [Canonical demo path] Define the canonical demo and validation flow | 🔴 | +| 99.5.2 | [Canonical demo path] Add or refine canonical run scripts for the demo path | 🔴 | +| 99.6.1 | [Packaging and developer setup tightening] Tighten packaging and local setup documentation around the golden path | 🔴 | +| 99.6.2 | [Packaging and developer setup tightening] Validate the first-run experience from the tightened docs | 🔴 | + +> Phase 99 progress: 0 / 13 + +--- + +## PHASE-100: CI and Quality Gate Hardening + +| ID | Task | Status | +|------|------|--------| +| 100.1.1 | [CI workflow audit] Inventory existing CI workflows, jobs, and triggers | 🔴 | +| 100.1.2 | [CI workflow audit] Map CI coverage to the supported product matrix | 🔴 | +| 100.2.1 | [Build matrix tightening] Tighten the CI build matrix around supported targets | 🔴 | +| 100.2.2 | [Build matrix tightening] Ensure release builds are exercised in CI | 🔴 | +| 100.3.1 | [Static analysis and formatting enforcement] Add or refine formatting enforcement | 🔴 | +| 100.3.2 | [Static analysis and formatting enforcement] Add or refine lint and static-analysis enforcement | 🔴 | +| 100.4.1 | [Test gate hardening] Audit which tests are currently gating merges | 🔴 | +| 100.4.2 | [Test gate hardening] Add or tighten core-path test gates | 🔴 | +| 100.5.1 | [Sanitizer and reliability jobs] Define a sanitizer and reliability-job strategy | 🔴 | +| 100.5.2 | [Sanitizer and reliability jobs] Add at least one practical sanitizer or reliability job | 🔴 | +| 100.6.1 | [Artifact and packaging checks] Verify CI artifact and packaging outputs for the supported path | 🔴 | +| 100.6.2 | [Artifact and packaging checks] Document what CI proves and what it does not prove | 🔴 | + +> Phase 100 progress: 0 / 12 + +--- + +## PHASE-101: Architecture Boundary Cleanup + +| ID | Task | Status | +|------|------|--------| +| 101.1.1 | [Architecture map audit] Map current subsystem boundaries from the repository tree | 🔴 | +| 101.1.2 | [Architecture map audit] Identify cross-layer violations and architecture ambiguities | 🔴 | +| 101.2.1 | [Boundary rule definition] Define target architectural layering and boundary rules | 🔴 | +| 101.2.2 | [Boundary rule definition] Publish boundary rules in architecture docs | 🔴 | +| 101.3.1 | [Directory/layout rationalization] Identify low-risk directory and layout rationalization opportunities | 🔴 | +| 101.3.2 | [Directory/layout rationalization] Execute one safe layout rationalization step | 🔴 | +| 101.4.1 | [Interface cleanup] Audit core interfaces and seams on the supported path | 🔴 | +| 101.4.2 | [Interface cleanup] Normalize one high-value interface family | 🔴 | +| 101.5.1 | [Naming and consistency pass] Audit naming inconsistencies in high-visibility architecture surfaces | 🔴 | +| 101.5.2 | [Naming and consistency pass] Apply a targeted naming consistency pass | 🔴 | +| 101.6.1 | [Legacy/experimental isolation] Identify legacy, preview, and experimental surfaces that need stronger isolation | 🔴 | +| 101.6.2 | [Legacy/experimental isolation] Document and implement one isolation improvement for non-core surfaces | 🔴 | + +> Phase 101 progress: 0 / 12 + +--- + +## PHASE-102: Observability and Reliability + +| ID | Task | Status | +|------|------|--------| +| 102.1.1 | [Logging audit] Inventory current logging patterns on the supported path | 🔴 | +| 102.1.2 | [Logging audit] Identify inconsistent log shapes and missing context | 🔴 | +| 102.2.1 | [Structured event schema] Define a structured event schema for the golden path | 🔴 | +| 102.2.2 | [Structured event schema] Apply the structured schema to one critical path | 🔴 | +| 102.3.1 | [Metrics surface expansion] Identify critical metrics for encode, network, decode, and render stages | 🔴 | +| 102.3.2 | [Metrics surface expansion] Expose missing metrics in at least one critical supported path | 🔴 | +| 102.4.1 | [Session and stream tracing] Add session correlation and trace identifiers to the supported path | 🔴 | +| 102.4.2 | [Session and stream tracing] Document how to interpret session traces | 🔴 | +| 102.5.1 | [Reliability diagnostics] Identify the highest-value reliability diagnostics gaps | 🔴 | +| 102.5.2 | [Reliability diagnostics] Improve one reliability diagnostic path and validate it | 🔴 | +| 102.6.1 | [Operational troubleshooting documentation] Write troubleshooting guidance keyed to logs, metrics, and checkpoints | 🔴 | +| 102.6.2 | [Operational troubleshooting documentation] Cross-link troubleshooting docs from support and onboarding surfaces | 🔴 | + +> Phase 102 progress: 0 / 12 + +--- + +## PHASE-103: Testing, Stress, and Soak Discipline + +| ID | Task | Status | +|------|------|--------| +| 103.1.1 | [Test inventory and gap analysis] Map existing tests to supported product areas | 🔴 | +| 103.1.2 | [Test inventory and gap analysis] Identify unsupported or unvalidated core-path code | 🔴 | +| 103.2.1 | [Core-path unit and integration strengthening] Add tests for the highest-risk core-path validation gap | 🔴 | +| 103.2.2 | [Core-path unit and integration strengthening] Ensure the canonical path has explicit regression coverage | 🔴 | +| 103.3.1 | [Adverse condition simulation] Define adverse-network and failure simulations for the supported path | 🔴 | +| 103.3.2 | [Adverse condition simulation] Add at least one adverse-condition simulation harness or job | 🔴 | +| 103.4.1 | [Soak test scaffolding] Create soak-test scaffolding for the supported path | 🔴 | +| 103.4.2 | [Soak test scaffolding] Document soak-test execution and result expectations | 🔴 | +| 103.5.1 | [Regression harness improvement] Audit regression harness ergonomics and reporting | 🔴 | +| 103.5.2 | [Regression harness improvement] Tighten regression harness output or fixtures | 🔴 | +| 103.6.1 | [Test documentation and reporting] Document the expected pre-release test suite | 🔴 | +| 103.6.2 | [Test documentation and reporting] Publish test result interpretation guidance | 🔴 | + +> Phase 103 progress: 0 / 12 + +--- + +## PHASE-104: Performance and Benchmark Proof + +| ID | Task | Status | +|------|------|--------| +| 104.1.1 | [Performance surface audit] Inventory performance-sensitive surfaces and current performance claims | 🔴 | +| 104.1.2 | [Performance surface audit] Define key metrics and benchmark environments | 🔴 | +| 104.2.1 | [Benchmark harness creation or normalization] Normalize the benchmark entrypoint and invocation flow | 🔴 | +| 104.2.2 | [Benchmark harness creation or normalization] Add reproducible benchmark execution instructions | 🔴 | +| 104.3.1 | [Baseline metric capture] Capture baseline metrics for the canonical path where feasible | 🔴 | +| 104.3.2 | [Baseline metric capture] Record measurement caveats and environment details | 🔴 | +| 104.4.1 | [Bottleneck analysis] Analyze baseline results for bottlenecks in the supported path | 🔴 | +| 104.4.2 | [Bottleneck analysis] Record validated optimization follow-ups without overcommitting | 🔴 | +| 104.5.1 | [Performance documentation] Write honest performance documentation tied to measured evidence | 🔴 | +| 104.5.2 | [Performance documentation] Cross-link performance docs from the supported-path surfaces | 🔴 | +| 104.6.1 | [Optimization follow-up queue] Prioritize the performance optimization backlog from measured evidence | 🔴 | +| 104.6.2 | [Optimization follow-up queue] Tag benchmark checkpoints for future regression tracking | 🔴 | + +> Phase 104 progress: 0 / 12 + +--- + +## PHASE-105: Security Posture and Trust Signals + +| ID | Task | Status | +|------|------|--------| +| 105.1.1 | [Security documentation audit] Audit current security documentation and policy signals | 🔴 | +| 105.1.2 | [Security documentation audit] Map security-relevant code touchpoints for the supported path | 🔴 | +| 105.2.1 | [Threat model definition] Draft a repository threat model for the supported product | 🔴 | +| 105.2.2 | [Threat model definition] Document trust boundaries and security assumptions in user-facing docs | 🔴 | +| 105.3.1 | [Auth and crypto implementation review] Review authentication and cryptography implementation touchpoints against docs | 🔴 | +| 105.3.2 | [Auth and crypto implementation review] Record unfinished, risky, or unreviewed security areas | 🔴 | +| 105.4.1 | [Security workflow and policy cleanup] Tighten `docs/SECURITY.md` and vulnerability-reporting guidance | 🔴 | +| 105.4.2 | [Security workflow and policy cleanup] Add explicit security review-status language to core docs | 🔴 | +| 105.5.1 | [Trust signal enhancements] Improve visible repository trust signals around security and support | 🔴 | +| 105.5.2 | [Trust signal enhancements] Document what is and is not security-reviewed | 🔴 | + +> Phase 105 progress: 0 / 10 + +--- + +## PHASE-106: Enterprise-Grade Repo Polish + +| ID | Task | Status | +|------|------|--------| +| 106.1.1 | [Root directory cleanup plan] Audit root-directory clutter, duplication, and first-contact confusion | 🔴 | +| 106.1.2 | [Root directory cleanup plan] Execute one low-risk root-level cleanup with validation | 🔴 | +| 106.2.1 | [Documentation style and consistency pass] Define concise documentation style rules for top-level docs | 🔴 | +| 106.2.2 | [Documentation style and consistency pass] Normalize high-visibility docs to the defined style | 🔴 | +| 106.3.1 | [Onboarding and contributor flow cleanup] Audit onboarding and contributor flow from first read to first change | 🔴 | +| 106.3.2 | [Onboarding and contributor flow cleanup] Tighten contributor and onboarding docs around the supported path | 🔴 | +| 106.4.1 | [Canonical command references] Consolidate canonical commands for setup, build, test, and demo flows | 🔴 | +| 106.4.2 | [Canonical command references] Validate canonical commands against actual scripts or entrypoints | 🔴 | +| 106.5.1 | [Public-facing repo presentation polish] Polish public-facing docs to emphasize proof over posture | 🔴 | +| 106.5.2 | [Public-facing repo presentation polish] Remove remaining high-visibility unsupported claims | 🔴 | + +> Phase 106 progress: 0 / 10 + +--- + +## PHASE-107: Release Readiness System + +| ID | Task | Status | +|------|------|--------| +| 107.1.1 | [Release process audit] Audit the current release process, artifacts, and repo signals | 🔴 | +| 107.1.2 | [Release process audit] Identify missing release-discipline components | 🔴 | +| 107.2.1 | [Versioning policy] Define a versioning policy appropriate for the supported product | 🔴 | +| 107.2.2 | [Versioning policy] Document version semantics and branch expectations | 🔴 | +| 107.3.1 | [Release checklist] Create a release checklist grounded in validation evidence | 🔴 | +| 107.3.2 | [Release checklist] Add release evidence requirements and result-capture guidance | 🔴 | +| 107.4.1 | [Known issues and blocker tracking] Define blocker severity levels and known-issue taxonomy | 🔴 | +| 107.4.2 | [Known issues and blocker tracking] Create known-issues and blocker tracking guidance | 🔴 | +| 107.5.1 | [Production readiness criteria] Define ship/no-ship criteria for the supported product | 🔴 | +| 107.5.2 | [Production readiness criteria] Cross-link release-readiness criteria from high-visibility docs | 🔴 | + +> Phase 107 progress: 0 / 10 + +--- + +## PHASE-108: Legendary Consistency Pass + +| ID | Task | Status | +|------|------|--------| +| 108.1.1 | [Terminology normalization] Build a terminology glossary from core product docs | 🔴 | +| 108.1.2 | [Terminology normalization] Normalize high-visibility terminology to the glossary | 🔴 | +| 108.2.1 | [Naming consistency audit] Audit naming consistency across visible interfaces and docs | 🔴 | +| 108.2.2 | [Naming consistency audit] Fix the highest-confusion naming mismatches | 🔴 | +| 108.3.1 | [Document cross-linking and truth-source cleanup] Consolidate truth sources and cross-links across core docs | 🔴 | +| 108.3.2 | [Document cross-linking and truth-source cleanup] Remove contradictory duplicate guidance from core docs | 🔴 | +| 108.4.1 | [Final support-claim audit] Audit final support and performance claims against evidence | 🔴 | +| 108.4.2 | [Final support-claim audit] Correct remaining unsupported, preview, or ambiguous claims | 🔴 | +| 108.5.1 | [Final polish pass] Apply the final consistency polish to key docs and repository surfaces | 🔴 | +| 108.5.2 | [Final polish pass] Run the final consistency validation sweep and close the program | 🔴 | + +> Phase 108 progress: 0 / 10 + +--- + +> Transformation program progress: 16 / 129 microtasks complete.