lanspread/PEER_CLI_SCENARIOS.md

Peer CLI P2P Scenarios

This matrix tracks the headless peer-to-peer contract exercised through lanspread-peer-cli. It intentionally avoids the GUI and uses direct connect for deterministic local runs; mDNS/macvlan remains an environment smoke path.

Scenario Matrix

ID	Scenario	Setup	Expected result
S1	Startup scan	Start one peer with fixture-alpha.	Peer emits local-peer-ready and local-games-updated; catalog fixture games are downloaded=true, installed=false, availability=Ready.
S2	Direct connect handshake	Start alpha and bravo, send alpha connect to bravo's ready address.	Both peers record one remote peer, no self-peer entry appears, and each peer receives the other's library.
S3	Remote aggregation	Empty client connects to alpha and bravo.	list-games shows remote-only games once; shared ggoo has peer_count=2, unique games have peer_count=1.
S4	Single-source download, no install	Empty client connected to bravo downloads bfbc2 with install=false.	Client emits got-game-files, download-begin, download-finished, then local bfbc2 is downloaded=true, installed=false; root files exist and local/ does not.
S5	Auto-install download	Empty client connected to bravo downloads cnctw with default install.	Download finishes, install begins and finishes, and local cnctw is downloaded=true, installed=true with local/fixture-payload.txt.
S6	Manual install and uninstall	After S4, client sends install bfbc2, then uninstall bfbc2.	Install marks bfbc2 installed and creates local/; uninstall removes local/ while preserving downloaded root files.
S7	Duplicate-source majority download	Empty client connects to alpha and bravo, then downloads shared ggoo.	Metadata from both peers validates by majority/plurality, download completes once, and installed state matches the install flag.
S8	Ambiguous metadata rejection	Two peers advertise the same game/version with conflicting file sizes.	Download fails with a download-failed event; no committed version.ini is left for the target game.
S9	Missing game	Client asks for a game none of its peers can serve.	CLI reports a deterministic command failure and emits no-peers-have-game; no local files are created.
S10	Shutdown and goodbye cleanup	Alpha and bravo are connected, then bravo shuts down.	Alpha receives peer loss/removal and remote games from bravo disappear.
S11	Same identity reconnect	Bravo restarts with the same state dir but a new port, then alpha connects to the new address.	Alpha has one bravo peer entry with the updated address, not duplicate identities.
S12	Transfer serving gates	A peer has a non-catalog, missing-sentinel, active-operation, or local/ path request.	The serving peer declines metadata/data; covered by unit tests where timing is too small for a stable CLI race test.

Run Log

No scenario evidence recorded yet.