refactor: prune unconsumed peer lifecycle events

An emit-vs-listen audit of the event surface showed the GUI is
state-as-source-of-truth: useGames renders the complete `games-list`
snapshot (full library + active_operations) and reconstructs status from
it, not from a stream of granular events. Several PeerEvents were emitted
but had no consumer at all -- no frontend `listen()` and no peer-cli
scenario assertion -- so they were pure dead weight that made the backend
look event-driven when it no longer is.

This prunes that dead surface in two parts.

1. Remove three PeerEvent variants with no consumer: InstallGameBegin,
   UninstallGameBegin, and RemoveDownloadedGameBegin. The operation-start
   transition is still observable via ActiveOperationsChanged (the
   snapshot already carries the Installing/Updating/Uninstalling/
   RemovingDownload kind), so nothing is lost. This drops their emit
   sites in handlers.rs, the begin-event assertions in the peer's
   lifecycle unit tests (the asserted sequence is now
   ActiveOperationsChanged(kind) -> LocalLibraryChanged ->
   ActiveOperationsChanged([]) -> *Finished), the peer-cli JSONL
   mappings (install-begin/uninstall-begin/remove-download-begin) plus
   the now-orphaned install_operation_name helper and InstallOperation
   import, and the matching Tauri handler arms.

2. Drop Tauri webview emits that no frontend listener consumed:
   peer-local-ready, game-download-begin, game-download-pre,
   game-download-finished, game-uninstall-finished, and
   peer-connected/-disconnected/-discovered/-lost. The log lines and all
   real side effects are kept (handle_got_game_files still forwards
   PeerCommand::DownloadGameFiles). The orphaned emit_peer_addr_event and
   handle_download_finished helpers and the now-unused SocketAddr import
   are removed. peer-runtime-failed is kept pending a decision on
   surfacing runtime failures in the GUI.

Why not re-wire instead: under state-as-source-of-truth, per-event UI
state is exactly the pattern this project abandoned. Live progress
already flows via game-download-progress, and the peer-cli's chunk,
timing-trigger, and transition assertions read events that are retained
(download-begin, download-chunk-finished, the *-finished/*-failed
terminals), so test coverage is unchanged.

Behavior change: none functional. The Tauri backend no longer emits
events nothing listened to; the GUI is unchanged. The peer-cli no longer
emits the three *-begin JSONL events. PeerEvent is a workspace-internal
UI-reporting type, not a wire-protocol type, so there is no protocol or
version impact and all consumers are updated in this commit.

Docs: PEER_CLI_SCENARIOS.md S39 no longer lists install-begin (with a
note that the start transition is visible via active-operations-changed),
and a dated Run Log entry records the removal. The historical 2026-05-18
run-log note is left intact as a dated observation.

Test Plan:
- just test: pass (incl. peer lifecycle event-sequence tests).
- just clippy: pass (-D warnings, all targets).
- just frontend-test: pass (11/11, incl. streamed-install gating/labels).
- just build: pass (release, no bundle).
- Not run: the Docker S39-S47 matrix (run_extended_scenarios.py); those
  scenarios never asserted the removed *-begin events, so coverage is
  unaffected. just fmt's tombi step needs network and was skipped; no
  TOML changed.

Refs: peer event-surface emit-vs-listen audit; no external consumers of
the removed events.
This commit was merged in pull request #28.
This commit is contained in:
2026-06-20 19:54:53 +02:00
parent c25dc7420e
commit 0b8e1e7f92
5 changed files with 24 additions and 178 deletions
+20 -1
View File
@@ -46,7 +46,7 @@ for deterministic local runs; mDNS/macvlan remains an environment smoke path.
| S36 | Catalog singleton beats stale majority | Five peers advertise one game; one peer has the catalog version and four peers have stale versions. | `list-games` reports `peer_count=1` and the catalog `eti_game_version`; all descriptors and chunks come from the singleton catalog-version peer, while stale peers remain hidden and contribute zero bytes. |
| S37 | Single-source download throughput | A source peer advertises a temporary catalog game with one sparse `2 GiB` `.eti`; an empty client downloads it with `install=false`. | The client emits `download-finished` with throughput measurements (`bytes`, `duration_ms`, `mib_per_s`, `mbit_per_s`), and the downloaded archive size matches the source. |
| S38 | First-play launch-setting stamping | `fixture-persona/css` ships a real RAR `.eti` whose tree buries a CRLF `SmartSteamEmu.ini` with a stub `PersonaName` line under `engine/bin/win64/steam_settings/`, plus a stub `account_name.txt` and `language.txt` under `profiles/local/`. A peer installs `css` (with `--unrar`), then sends `play css` with a username and language, then `play css` again. | After install the marker `games/css/launch_settings_applied` is absent and the stub files are intact under `local/`. The first `play` returns `already_applied=false` with `account_name_written`, `language_written`, and `persona_name_written` all true; the deep `SmartSteamEmu.ini` `PersonaName` value becomes the username with its `\r\n` ending and sibling lines preserved, `account_name.txt` becomes the username, `language.txt` becomes the passed language, and the marker now exists. A second `play` returns `already_applied=true`, rewrites nothing, and leaves the files untouched even if their values were reset externally. |
| S39 | Streamed install without keeping archive payload | Empty client connects to `fixture-bravo`, then sends `stream-install cnctw`. The source has real RAR `.eti` payload entries under `bin/` and `data/`; the receiver uses the container-bundled `unrar` stream provider. | Client emits `download-begin`, streamed `download-chunk-finished`, `download-finished`, `install-begin`, and `install-finished`. Local `cnctw` is `downloaded=false`, `installed=true`, `availability=LocalOnly`; root `version.ini` and `.eti` are absent; `local/bin/cnctw-payload.bin` and `local/data/cnctw-assets.dat` match `unrar p` output by SHA-256; the source reports no active outbound transfer for `cnctw` after completion. |
| S39 | Streamed install without keeping archive payload | Empty client connects to `fixture-bravo`, then sends `stream-install cnctw`. The source has real RAR `.eti` payload entries under `bin/` and `data/`; the receiver uses the container-bundled `unrar` stream provider. | Client emits `download-begin`, streamed `download-chunk-finished`, `download-finished`, and `install-finished` (the install-start transition is observable via `active-operations-changed`; there is no separate `install-begin` event). Local `cnctw` is `downloaded=false`, `installed=true`, `availability=LocalOnly`; root `version.ini` and `.eti` are absent; `local/bin/cnctw-payload.bin` and `local/data/cnctw-assets.dat` match `unrar p` output by SHA-256; the source reports no active outbound transfer for `cnctw` after completion. |
| S40 | Streamed install receiver is not a peer source | After S39, a third peer connects only to the streamed-install receiver. | The third peer may see the receiver's local-only summary in peer snapshots, but `list-games` remote aggregation does not expose `cnctw` as downloadable, `peer_count` remains zero/absent, and attempting `download cnctw` fails with no local files created. |
| S41 | Solid archive streamed install | Empty client connects to a peer serving `fixture-solid/cnctw`, whose `.eti` is a real solid RAR archive. The receiver uses the container-bundled `unrar` stream provider. | The fixture is verified as solid with `unrar lt`; streamed install finishes with `downloaded=false`, `installed=true`, `availability=LocalOnly`; root archive and `version.ini` are absent; streamed byte count equals the extracted solid entries; local payload SHA-256 hashes match `unrar p` output. |
| S42 | Streamed install whole-stream retry | Empty client connects to two peers serving the same catalog-version `cnctw`: one broken source whose `--unrar` path is missing, followed by one good source. | The broken source sorts before the good source in retry order, contributes zero chunks, and the good source completes a fresh whole-stream attempt. The final state is local-only installed, no root archive/sentinel, no `.local.installing`, byte count matches the extracted entries, and payload hashes match the good source. |
@@ -143,6 +143,25 @@ Use S39-S41 to pin down low-disk streamed installs:
## Run Log
### 2026-06-20 - Prune Dead Lifecycle Events
- Code under test removed the unconsumed `InstallGameBegin`, `UninstallGameBegin`,
and `RemoveDownloadedGameBegin` `PeerEvent` variants (and their peer-cli JSONL
`install-begin`/`uninstall-begin`/`remove-download-begin` events), plus the
Tauri webview emits that no frontend listener consumed (`peer-local-ready`,
`game-download-begin`, `game-download-pre`, `game-download-finished`,
`game-uninstall-finished`, `peer-connected`/`-disconnected`/`-discovered`/`-lost`).
`peer-runtime-failed` was kept pending a UI decision.
- Rationale: the GUI is state-as-source-of-truth (it renders the `games-list`
snapshot), and no scenario asserted these begin events; the install, uninstall,
and removal start transitions stay observable via `active-operations-changed`.
- Contract update: the S39 row no longer lists `install-begin`. Older run-log
entries below predate the removal and are left intact as historical records.
- Gates: `just test`, `just clippy`, `just frontend-test`, and `just build`
passed. (`just fmt`'s `tombi` step needs network and was skipped; no TOML
changed.) The Docker S39-S47 matrix was not re-run for this cleanup; S39-S47
never asserted the removed begin events, so coverage is unchanged.
### 2026-06-07 - Catalog-Version Matrix Alignment (S1-S47)
- Code under test aligned checked-in fixture `version.ini` sentinels with the