lanspread/crates/lanspread-peer/ARCHITECTURE.md

# lanspread-peer architecture

The peer uses mDNS discovery, authenticated QUIC transport, responder-owned
metadata snapshots, and catalog-authorized file transfers. Wire protocol 8 and
ALPN `lanspread/8` are the only supported wire mode; there is no legacy decode,
fallback, or compatibility shim.

## Goals (unchanged)

- Local LAN discovery via mDNS.
- QUIC + JSON messages for control, raw streams for file data.
- UI drives operations through `PeerCommand`, peers remain headless.
- Peers can appear/disappear at any time without data loss.

## Installation identity and QUIC authentication

- One installation-local Ed25519 key signs one self-issued TLS certificate.
  `PeerId` is BLAKE3 over the certificate's complete canonical DER
  SubjectPublicKeyInfo, encoded as 52 lowercase unpadded RFC 4648 base32
  characters. It is not a UUID, display name, IP address, or wire assertion.
- The desktop app stores a strict version-1 record at `peer-identity-v1.json` in
  its Tauri app-data directory. The record binds the Ed25519 certificate,
  private key, SPKI-derived `PeerId`, and exact SAN. Reads and publication do
  not follow symlinks or reparse points, creation is no-clobber, corrupt bytes
  are quarantined before replacement, and private material is kept at mode 0600
  where the platform supports Unix modes.
- Persistence failure produces a typed `Ephemeral` outcome and a fresh identity
  for that runtime; it never falls back to another peer-ID scheme. The peer CLI
  can instead select an existing record with `--identity-file`; that path is
  loaded strictly and is never repaired, replaced, or generated implicitly.
- Identity state assumes one normal application owner for its app-data directory
  and deliberately has no cross-process identity lease. Retained no-follow
  handles contain path traversal and external-target mutation, and publication
  does not overwrite an existing winner. A concurrent same-user writer can still
  cause availability or continuity loss during quarantine; it is outside the
  supported ownership model.
- QUIC uses the rustls provider with TLS 1.3 only. Every outbound operation
  carries a `PeerEndpoint { peer_id, addr }`; the expected ID is encoded in an
  exact SNI name, checked against the responder certificate SPKI, and the real
  TLS 1.3 CertificateVerify signature is delegated to rustls. ALPN is
  `lanspread/8`. Client resumption and 0-RTT are disabled; the server issues no
  tickets and sends no early or half-RTT data.

## Peer lifecycle and message flow

### 1) Startup and advertise

- Start QUIC server.
- Advertise via mDNS with TXT records:
  - `peer_id` (the canonical SPKI-derived ID)
  - `proto_ver`
  - optional `hostname`

### 2) Discovery and handshake

When a peer is discovered:

1. Parse `peer_id`, address, and `proto_ver` into a candidate `PeerEndpoint`.
   Discovery is not authentication and does not add the peer to `PeerGameDB` or
   emit UI membership events. The mDNS ingress queue and active candidate
   negotiations are each capped at 64.
2. Reserve a candidate negotiation lease before queueing or awaiting work, then
   establish a TLS-pinned connection to that exact endpoint. Missing or non-v8
   records are rejected, and neither an ephemeral QUIC source port nor a payload
   can replace the candidate listener address.
3. Send the empty `Hello` pull request. The pinned responder returns a
   `HelloSnapshot` containing a `PeerStateSnapshot` with `runtime_session_id`,
   `library`, and `call_to_play`: only that responder's local library and local
   Call-to-Play author slice.
4. Decode the strict bounded wire shape, then validate the library and
   Call-to-Play domains independently. Commit the endpoint and each valid domain
   only if the candidate lease is still current for both peer ID and address.
   This domain isolation lets an invalid remote Call-to-Play slice be cleared or
   preserved according to its session without discarding a valid library.
5. Assign a fresh endpoint generation to every successful authentication.
   Dropped, failed, or superseded work releases its candidate claims, and a late
   result cannot mutate a newer generation.

### 3) Steady state

- Successful liveness probes update `last_seen` only when both the typed
  endpoint and its authenticated generation are still current. Stale probes
  cannot refresh or remove a reauthenticated endpoint.
- `Ping` receives a `Pong` carrying `PeerRevisions` with the runtime-session ID
  and both domain revisions. A session or revision mismatch schedules a full
  pinned pull, so idle liveness heals dropped change hints.
- Local library or Call-to-Play changes send cheap revision hints. Hints are
  untrusted and lossy: unknown claims are ignored, and a known claim can only
  coalesce a pull from the claimed peer's already authenticated endpoint.
- The state-sync scheduler caps its ingress and tracked peers at 64, coalesces
  work for five seconds, and runs at most eight pinned pulls and eight hint
  sends concurrently. Child work is drained lexically on shutdown.
- The server admits at most 64 unauthenticated handshakes, 64 established
  connection scopes, and 32 control streams per connection. Each control stream
  accepts one frame followed by request EOF and sends at most one response; the
  frame cap is 8 MiB and control I/O has ten-second deadlines.

### Call to Play replication

Call to Play is transient, responder-owned state. Each peer serves exactly one
local author snapshot:

```text
CallToPlayAuthorSnapshot { revision, display_name, events }
CallToPlayAuthorEvent { id, call_id, at, action }
```

The outer `PeerStateSnapshot` owns the runtime-session ID. A `CallId` encodes
the creator's typed `PeerId` plus a 128-bit nonce. The UI supplies only a local
intent and current display name; the peer core generates call/event nonces and
timestamps. Identity and display name are not repeated inside events. Creator
actions (`Create`, `Start`, `Cancel`, and `AddTime`) must come from the
`CallId.creator`; participant authors may contribute only participant actions.

The receiver assigns author identity from the pinned `PeerEndpoint`, validates
and normalizes the whole author slice off-lock, then commits it against that
endpoint's current generation and runtime session. For the same session, only a
higher revision replaces the slice; an equal identical snapshot is a no-op, an
equal different snapshot is a conflict, and a lower revision is stale. A new
authenticated session clears the previous slice before accepting valid new
state. Invalid same-session state preserves the last valid slice, while invalid
new-session state leaves that author absent.

Participant events are retained but hidden until the creator's direct author
slice supplies the call root. Removing a participant removes only that author's
rows; removing the creator hides the entire call. Because every snapshot is
served only by its author and attributed from the pinned responder, there is no
union merge, relay, live-event push, acknowledgement, or author claim on the
wire. The UI receives a deterministic complete replacement view.

Unresolved call history is removed as a whole after the deadline plus five
minutes; terminal history is removed as a whole after `Start` or `Cancel` plus
15 minutes. No tombstone survives pruning. Pruning a local slice advances its
revision before a snapshot or `Pong` is served, allowing peers to discover the
removal. The store caps total authors at 64, events per author at 4,096, and one
encoded author snapshot at 4 MiB, with reserved capacity for terminal actions.

### 4) Shutdown

- Cancellation stops admission, drains all lexically owned connection, stream,
  state-sync, operation, and mDNS children, closes the shared endpoints, and
  joins the supervisor.
- There is no `Goodbye` control message. Pinned liveness failure and stale
  generation-conditional removal are authoritative for departure.

## Library sync protocol

The responder's full library slice is
`LibrarySnapshot { revision, games: Vec<GameAvailability> }`, where each sorted,
unique availability row contains only `game_id` and the catalog-derived exact
`ContentId`. A snapshot contains at most 4,096 games. It does not carry titles,
versions, paths, sizes, file lists, hashes chosen by the peer, installed state,
or another peer's availability.

The empty `Hello` request always returns the responder's current complete slice.
For the same runtime session, a higher revision atomically replaces the cached
slice; lower or equal stale work cannot roll it back. A new authenticated
runtime session resets the old domain before its candidate snapshot is
considered. `LibraryChanged(ChangeHint)` carries only an untrusted claimed
identity, runtime session, and revision. It never mutates a library directly and
has no delta payload. A pinned `Pong` revision mismatch schedules the same full
pull.

## Local library publication

- Only real local availability changes advance the revision and schedule a hint;
  there is no periodic list broadcast.
- Filesystem events are gated per game ID instead of time-debounced:
  - an active operation lock drops events for that game;
  - a rescan already running for the ID sets a rescan-pending flag;
  - the running rescan loops once more when that flag was set.
- Local library scans emit `LocalLibraryChanged` only for real library changes,
  except that accepted game-directory changes can force a UI snapshot for the
  new path without changing peer availability.
- Active operation mutations emit `ActiveOperationsChanged` from the mutation
  path instead of riding on local library scans.
- The remote UI projection is a wholesale replacement derived from all current
  authenticated per-peer slices; two peers offering the same game remain
  distinct exact-content sources.

## Local game scanning: fast and low cost

### Strategy

1. Maintain a persistent revisioned on-disk index of local summaries and cheap
   per-game fingerprints (root-level `version.ini` contents/mtime, root-level
   `.eti` name/size/mtime, `local/` presence, and recovery state).
2. Poll a bounded non-recursive metadata snapshot once per second and update
   only changed games.
3. Keep a 300-second fallback scan to recover from missed events.

### Fast-path scanning

- On startup, list only top-level game directories.
- For each game, read a cheap fingerprint:
  - root-level `.eti` file names, sizes, and mtimes
  - root-level `version.ini` mtime
  - presence of `local/` as a directory
- If the fingerprint is unchanged, reuse the cached local summary.
- Only run a recursive scan for new or changed games.

## Local State and Recovery

Downloaded and installed are independent predicates:

- `downloaded` is true only when `<game_root>/version.ini` exists as a regular
  file. The sentinel is written last through `.version.ini.tmp` and atomic
  rename. The old sentinel is parked before a pending ownership set is
  published; recovery restores it only when a valid baseline proves payload
  mutation never started.
- `installed` is true when `<game_root>/local/` is a directory. The contents of
  `local/` are user-owned and are skipped by manifests, fingerprints, and file
  serving.
- Install and update transactions unpack into staging, then overwrite the first
  discovered game-provided `account_name.txt` and `language.txt` files under the
  staged tree from launcher settings before promoting it to `local/`.

Reserved per-game paths:

- `.version.ini.tmp` and `.version.ini.discarded` are download transaction
  scratch files. Startup recovery interprets them together with the durable
  ownership journal rather than sweeping them independently.
- `.local.installing/` is extraction staging.
- `.local.backup/` holds the previous install while an update or uninstall is in
  flight.
- `games/<game_id>/install_intent.json` in the configured state directory is the
  atomic per-game intent log.
- `games/<game_id>/download_ownership/v1-<root_digest>/record.json` in that
  state directory records the last committed and any pending downloader-owned
  regular-file set and its exact catalog content ID. The namespace is derived
  from one canonical configured games directory, and the record retains the full
  lossless root identity. Same-ID state for different configured roots therefore
  remains independent.
- `.lanspread_owned` inside `.local.*` directories proves Lanspread ownership
  when no active intent independently proves transaction ownership.

Downloaded-file removal is not an uninstall transaction. For a catalog ID that
is a single direct child of the configured game directory, it requires a valid
ownership record and regular root-level `version.ini`, and refuses `local/`,
`.local.installing/`, or `.local.backup/`. It journals an empty pending
generation, deletes only committed downloader-owned files and the sentinel, and
keeps the game root plus every unknown file or directory.

The state layout is game-first: root namespaces live under each game ID rather
than under a global root tree. A former singleton ownership record is migrated
once into its derived namespace with copy-first durable publication. Singleton
state is not accepted as a parallel runtime format, and conflicting or split
migration evidence fails closed.

Recovery reads app-state `install_intent.json` and combines the recorded active
intent with the observed `local/`, `.local.installing/`, and `.local.backup/`
state. Intent states `Installing`, `Updating`, and `Uninstalling` prove
ownership of the corresponding reserved directories even if the marker was not
flushed before a crash. Settled state is represented by absence of the intent;
markerless `.local.*` directories are then left untouched.

Legacy `.lanspread/`, `.lanspread.json`, `.lanspread.json.tmp`,
`.softlan_game_installed`, and `local/.softlan_first_start_done` files are
handled only by the dedicated pre-start migration phase. Normal operation does
not read legacy state paths.

### Result

Most scans become O(number of game dirs), with full recursion only when needed.

## File manifests and downloads

- Tauri and the peer CLI inject one immutable `CatalogBundle`: `game.db` defines
  catalog identity/version, the mandatory compact
  `manifests/catalog-content-index-v1.jsonl` maps every exact catalog row to its
  expected `ContentId` and Stream Install capability, and
  `manifests/<game_id>.json` defines canonical paths, kinds, sizes, 128 MiB
  chunks, and BLAKE3 values. The index has exact database coverage and is loaded
  once; manifest bodies remain on demand and must recompute both indexed fields.
  Disk body loads and full validation recheck the durable publication marker
  before and after their work. Runtime peers cannot add catalog entries or
  replace that byte authority.
- Authenticated remote-availability joins use the compact index only. Unknown or
  mismatched `(game_id, content_id)` pairs are rejected without filesystem I/O
  or manifest parsing; actual serving, download planning, and Stream Install
  still load and validate the full body.
- The local catalog artifact is converted into a `ValidatedDownloadManifest`
  before any destination mutation. It contains canonical game-root-relative
  paths and rejects aliases, reserved state, shape conflicts, and bounded-size
  violations as one unit. Remote peers never define the storage plan.
- Source selection requires the exact catalog `(game_id, content_id)` pair from
  an authenticated peer's current library slice. Every ordinary chunk request
  repeats the exact `ContentId`, `CanonicalCatalogPath`, offset, and length.
  There is no version-only or address-only eligibility adapter.
- A new manifest target that already exists without prior committed ownership is
  rejected before the sentinel, ownership journal, or payload is mutated.
- Download mutation holds a capability handle for the direct catalog game root.
  Directory components and final files are reopened relative to that handle
  without following links or Windows reparse points; chunk writes and checks use
  the same opened file handle.
- Downloads hash every chunk, including the buffered `version.ini`, as it is
  received and require the catalog BLAKE3 value, exact length, and exact end of
  stream. One absolute ten-minute application deadline covers the complete
  open/request/receive/check lifecycle of each ordinary chunk.
- An integrity failure quarantines `(PeerId, content_id)` in shared memory for
  the rest of that peer runtime, independent of address changes. Transport
  failures remain retryable without quarantine. Each failed chunk may try every
  distinct eligible peer identity once; there is no separate numeric retry cap.
- A no-transfer local shortcut is allowed only when settled ownership records
  the exact expected committed content ID. A matching `version.ini` alone, or a
  legacy/pre-content-ID record, is not catalog-content proof.
- A game is transferable only when its ID is in the catalog, no operation is
  active for that ID, and the root-level `version.ini` sentinel exists.
- The sender admits only an exact catalog path and, for ranged requests, an
  exact catalog chunk range before opening the retained no-follow file handle.
- `local/` paths are never served, even if a stale or malicious manifest request
  asks for them.
- Cancelling or recovering a download removes only paths named by its durable
  ownership journal and its validated pending manifest. Unknown user files,
  `local/`, and install transaction metadata are preserved, so a cancelled
  update of an installed game settles as local-only.

### Streamed install integrity

- Low-disk streamed installs request archive-derived file bytes from one peer
  and write them directly into the install transaction staging directory.
- A sender admits Stream Install only for a manifest with verified extracted
  output and only when its direct regular root `.eti` set exactly equals the
  catalog archive set. Missing or extra archives stop before the extraction
  provider receives authority.
- The Stream Install request names the exact catalog `ContentId`. All
  path-bearing frames, including archive names, use `CanonicalCatalogPath` and
  the fallible checked decoder distinguishes malformed framing from an explicit
  sender `Error` frame.
- The receiver independently requires the exact catalog archive set and the
  complete extracted path/kind/size set. It hashes every regular file with
  BLAKE3 while writing and verifies every expected entry before commit. Regular
  files may occur only once across the entire archive set; repeated directory
  entries are allowed because they carry no bytes. RAR CRC32 remains only an
  early corruption signal, not an authority boundary.
- Integrity failures quarantine the source for that catalog content and retry a
  fresh transaction from another eligible peer. Transport failures retry without
  quarantine; local I/O and cancellation stop. Every failed attempt rolls back
  before the next source begins.
- After complete catalog verification, account/language/persona settings are
  rewritten in staging before promotion. The one-shot launch-settings marker is
  written only after successful promotion; if it cannot be written, first play
  safely retries the rewrite.
- A game without a verified extracted-file manifest neither offers nor accepts
  Stream Install. There is no CRC32-only fallback.

## Catalog publication and packaging

- `lanspread-catalog-publisher` generates production manifests and their
  complete compact identity index beside the canonical packages, independently
  rebuilds/verifies each selected artifact, and uses a durable corpus marker so
  an interrupted body/index publication fails closed. Incremental generation
  requires an existing exact indexed corpus and atomically republishes the full
  index after the selected bodies. After it owns the marker, it freshly
  validates every unselected body/index pair before deriving that mixed index;
  no pre-marker snapshot can roll another completed publication backward.
- `lanspread-fixture-catalog` is a separate test-only generator. It derives
  reduced peer-CLI `game.db` files and manifests from explicitly selected
  fixtures; those outputs are development and acceptance-test authority only.
- Tauri fixture builds require both the exact committed development resource map
  and `LANSPREAD_USE_FIXTURE_CATALOG=1`. Every other build mode defaults to the
  production resource map, and the custom production profile cannot be
  downgraded to fixtures.
- Production packaging requires the complete production `game.db`/manifest
  corpus to pass `check --all`. The canonical production packages and their 186
  generated manifests are not present in this checkout, so that gate remains
  intentionally blocked; fixture success is not production completion.

## Fault tolerance rules

- Every authenticated peer is keyed by `PeerId`, not by IP address.
- An authenticated `PeerEndpoint` retains the candidate or explicitly supplied
  listener address. Payload fields and ephemeral QUIC source ports cannot
  rewrite it, and no network caller can dial an address without the expected
  responder ID.
- Every successful authentication assigns a fresh endpoint generation. Refresh,
  liveness update, and stale removal are conditional on the exact endpoint and
  generation they observed.
- Runtime-session IDs and per-domain revisions prevent delayed snapshots from
  rolling state back across restart or endpoint replacement. Change hints never
  bypass the pinned pull and generation checks.
- A generation-conditional authenticated departure removes that peer's library
  and Call-to-Play slices and publishes complete replacement views. Ordinary
  short-lived QUIC connection closure is not roster departure.
- Protocol 8 is strict and current-only. Unknown fields, noncanonical typed IDs
  or paths, duplicate/unsorted library rows, oversized domains, extra control
  frames, and v7 messages are rejected instead of adapted.