VoxVera/docs/roadmap-platform-parity.md

Platform Parity Roadmap

This roadmap focuses on one question:

How do we expand VoxVera beyond Linux without overstating reliability, while still converging on real cross-platform parity for Tor hidden-service hosting?

Strategic Principle

Parity is not a packaging milestone. It is a runtime-contract milestone.

Every platform must eventually implement the same hosting contract:

1. install VoxVera
2. ensure Tor and OnionShare are available
3. build site assets
4. serve the hidden service
5. preserve .onionshare-session
6. recover hosting after reboot, login, suspend, or offline periods
7. surface logs and status

Package formats should inherit that contract. They should not define independent behavior.

Phase 0: Truth Alignment

Goal: bring repo claims, docs, and release posture into line with current reality.

Deliverables:

• canonical support matrix
• machine-readable support declaration
• installer/package warnings for experimental paths
• README and docs aligned to the actual supported target

Definition of done:

• no docs imply parity that tests do not support
• every platform surface has an explicit support tier
• release artifacts are not treated as proof of hosting reliability

Phase 1: Harden Linux As Reference

Goal: make Linux CLI with systemd --user the clearly defensible model that other platforms copy.

Work items:

1. Add voxvera doctor for runtime validation.

   • Check Tor reachability.
   • Check OnionShare availability.
   • Check start-all surfaces.
   • Check autostart timer installation.
   • Check host directories and session files.

2. Add voxvera autostart status.

   • Show service and timer files.
   • Show whether the timer is enabled.
   • Show next/last run timestamps if available.

3. Normalize Linux log/status guidance.

   • Document host log paths.
   • Document timer/service status commands.
   • Document expected recovery flow after reboot/network loss.

4. Validate restart behavior.

   • fresh install
   • first serve
   • reboot
   • suspend/resume if possible
   • temporary offline period followed by reconnect

Definition of done:

• Linux remains the only supported path until the above evidence exists and is documented.

Phase 2: Platform Adapter Layer

Goal: stop encoding platform logic in ad hoc installer scripts.

Recommended structure:

• voxvera/platforms/base.py
• voxvera/platforms/linux.py
• voxvera/platforms/macos.py
• voxvera/platforms/windows.py
• voxvera/platforms/docker.py

Each adapter should define:

• support tier
• Tor discovery strategy
• OnionShare discovery strategy
• state root
• autostart installation strategy
• autostart status strategy
• log/status surface
• known limitations

CLI surfaces to add:

• voxvera doctor
• voxvera platform-status
• voxvera autostart
• voxvera autostart status
• voxvera autostart uninstall

Definition of done:

• shell installers become thin wrappers over shared Python logic instead of owning runtime policy themselves

Phase 3: Docker Beta Candidate

Goal: make Docker a coherent, testable deployment surface.

Decisions to settle:

• single-container runtime vs compose-based runtime
• host Tor vs container Tor
• log and state persistence model

Recommended direction:

• keep runtime state under one explicit volume root
• document restart policy clearly
• make health and recovery behavior observable

Validation checklist:

• container restart preserves onion identity
• host reboot with restart policy restores hosting
• state remains in mounted volume
• logs remain inspectable

Promotion target:

• experimental -> beta

Phase 4: macOS CLI

Goal: establish one honest CLI-based macOS hosting model before packaging.

Work items:

1. define Tor discovery strategy
2. define OnionShare discovery/install strategy
3. validate manual build + serve
4. implement and validate launchd recovery
5. document known limitations

Promotion target:

• remain experimental until launchd recovery is validated
• move to beta only after login/reboot/offline recovery evidence exists

Phase 5: Windows CLI

Goal: establish one canonical Windows runtime model before claiming package parity.

Work items:

1. unify binary naming across installer, Chocolatey, docs, and release assets
2. define Tor discovery strategy
3. define OnionShare discovery strategy
4. validate manual build + serve
5. implement Task Scheduler recovery path
6. add Windows-specific status/log guidance

Promotion target:

• remain experimental until scheduled recovery and state persistence are proven
• move to beta only after reboot/login/offline recovery evidence exists

Phase 6: Electron GUI Convergence

Goal: make the GUI a frontend to the supported runtime, not a separate runtime.

Work items:

1. route the GUI through shared CLI/runtime surfaces
2. reduce duplicated Tor startup behavior
3. add visibility for:
   • Tor status
   • OnionShare status
   • hosting status
   • onion URL
   • logs
4. make window-close behavior explicit and safe

Promotion target:

• GUI remains experimental until it stops diverging from the CLI runtime contract

Phase 7: Package Surface Promotion

Goal: package formats should become trustworthy wrappers around validated runtimes.

Work items:

1. Debian package

   • declare actual runtime dependencies
   • validate install + host + recovery path

2. AppImage

   • decide whether it is distribution-only or a real hosting target

3. Homebrew

   • fix artifact URL/sha/version policy
   • clarify whether it installs a hosting target or just a CLI

4. Chocolatey

   • align artifact naming and installer semantics

5. Flatpak

   • decide whether Tor/OnionShare can be supported sanely in-sandbox

Rule:

• no package surface should be promoted above the support tier of its underlying runtime

Testing Program

1. Unit tests

• config/state logic
• autostart file generation
• platform adapter selection

2. Mocked integration tests

• serve
• autostart
• doctor
• platform-status

3. Platform smoke tests

• fresh install
• build
• serve
• persist identity
• restart
• recover

Current smoke target names:

• linux-cli
• macos-cli
• windows-cli
• docker-cli

These target names are contract-level validation entry points. Only linux-cli currently represents a supported hosting path; the others should be used to validate experimental posture and dependency discovery on their native platforms until their recovery behavior is proven.

4. Release checks

• support matrix is current
• docs match support tiers
• artifact names match scripts and package manifests

Immediate Next Tasks

1. Add voxvera doctor.
2. Add voxvera autostart status.

Native Validation Assets

The repo now includes concrete native-host validation docs for the two major experimental desktop targets:

• docs/macos-validation-checklist.md
• docs/windows-validation-checklist.md
• docs/native-tester-guide.md

These should be used for the first real macOS/Windows validation cycles so testers capture the runtime evidence needed for future tier promotion. 3. Add the platform adapter scaffold. 4. Capture Linux reboot/offline recovery validation steps in docs and CI notes. 5. Pick Docker's canonical runtime model. 6. Normalize Windows binary naming before further Windows work.

Non-Goals

• claiming parity before recovery behavior is validated
• treating package availability as support proof
• maintaining separate runtime semantics in GUI vs CLI