# 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. Advertised addresses must be unicast with a nonzero port; multicast, broadcast, and unspecified targets are dropped before any handshake packet is sent. The mDNS ingress queue and active candidate negotiations are each capped at 64, and one observed response IP may hold at most 8 active-or-cooling candidates. The advertised A/AAAA target is never used as provenance, so one host cannot escape the budget by rotating target addresses, peer IDs, or ports. The vendored mDNS daemon also caps cached records at 1,024 globally and 128 per response IP, with at most 4,096 deduplicated timers. 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. After the pinned Hello succeeds, at most eight committed identities may reside at one stored endpoint IP, alongside the global 64-peer limit. This authenticated residency bound is separate from the pre-authentication mDNS candidate quota; a ninth identity is rejected without evicting an existing address owner, and removing a peer releases its slot. 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, a hint is honoured only when it arrives from the IP address at which the claimed peer was authenticated, and a known claim can only coalesce a pull from the claimed peer's already authenticated endpoint. Requesters are anonymous, so this source binding is what stops a third host from choosing which peers this node pulls. - 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. One observed IP may start at most 8 handshakes during one 3-second handshake window, before TLS and established-connection leases exist; the source ledger itself holds at most 256 IPs. One observed IP may retain at most 8 connections, 8 of the 16 global control tasks, 8 of the 48 global bulk tasks, and 1 of the 2 Stream Install providers. Each control stream accepts one frame followed by request EOF and sends at most one response. Inbound request frames are capped at 64 KiB (the QUIC receive window per server stream matches it), response frames at 8 MiB, and control I/O has ten-second deadlines. Response buffering permits at most 8 MiB per endpoint IP within one shared 32 MiB pool. Wire collections (library games, Call to Play author events) are deserialized through a bounded visitor that materializes at most one element past the semantic limit and discards the rest, so an oversize frame cannot claim more memory than a valid one before validation rejects it. ### 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. - After application children drain, endpoint tasks stop and join immediately; exit does not wait for cancelled handshakes or closed connections to exhaust their transport timers. - 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 }`, 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. Admission withdraws network availability under the operation and library locks, then emits the active operation before the withdrawn `LocalLibraryChanged` UI snapshot. This keeps the game visible as busy while peers can no longer request its changing files. - 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. - Snapshot and recursive work has explicit entry, game, depth, byte, file-size, and elapsed-time ceilings. Failure retains the previous complete state. Poll failures back off from one second to five minutes per attempted root; a root switch resets that delay once. ## Local State and Recovery Downloaded and installed are independent predicates: - `downloaded` is true only when `/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 `/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/`. - Launch-settings discovery uses one bounded traversal, reads at most 1 MiB per INI and 64 MiB in aggregate under the same ten-minute clock, and finishes all candidate reads before its first write or marker publication. 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//install_intent.json` in the configured state directory is the atomic per-game intent log. Every `games//` path is derived from a game ID that satisfies the catalog's portable component rules; the public `setup_done_path` and the launch-settings entry points validate the ID before joining it, and legacy migration refuses a games-folder directory whose name would not pass. - `games//download_ownership/v1-/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/.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. Outbound serving (chunk and Stream Install admission) also gates on the compact index and in-memory local readiness first and then reads the manifest body from the validated cache only: every publishable game's body was primed before its library revision became visible, so an anonymous request can neither trigger a disk read nor populate the manifest cache. Download planning on the requesting side still loads and validates the full body on demand. - 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 at most eight distinct authenticated identities at distinct endpoint IPs. All retries share one nonrenewable 20-minute window created after the initial failure; an individual attempt still has the earlier ten-minute limit. - 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. ### Ordinary install extraction - `install`/`update` extract every current direct regular root `.eti` archive with the external `unrar` unpacker into the staging directory. Downloaded archives were BLAKE3-verified, but the ordinary path deliberately accepts later local replacements and extra archives for the S33 workflow. - `unrar` runs with `-ol-`, so symbolic-link entries are skipped, and the staging tree is walked without following links before promotion. Any symlink (or reparse point on Windows) aborts the transaction and rolls staging back, so a link can never redirect later launch-time rewrites or uninstall. ### 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. - Provider egress has one nonrenewable deadline of ten minutes plus the exact catalog streamed bytes at 1 MiB/s, so large valid games are finite without a fixed ten-minute whole-transfer cutoff. - 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. At most four distinct endpoint IPs are attempted. Every attempt shares a catalog-sized total deadline of ten minutes plus two copies of the expected streamed bytes at 1 MiB/s. The ten-minute inactivity timer refreshes only after a nonempty, catalog-checked file chunk is written. 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-production-catalog` creates a production `game.db`, manifests, and complete compact identity index in staging, validates that authority with the application loader, and atomically replaces the generated catalog directory. Its default selection requires every game and exact version from the checked-in source database. Independent explicit modes may omit missing package directories or accept package versions that differ by updating the copied database. The generated manifests and database still form one exact set, and the source database is never modified. - `lanspread-catalog-publisher` incrementally regenerates selected manifests in an existing exact indexed corpus. After it owns the durable publication marker, it freshly validates every unselected body/index pair before deriving and atomically publishing the complete 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. - `just run` uses the existing production catalog. `just run-local GAMES_DIR` creates a separate cached catalog from the supplied files, allowing missing packages and package versions that differ from the metadata database. Local builds require a distinct compile-time opt-in and resource map, are rejected by the production profile and bundled builds, and use separate app settings. Their startup game directory is compiled in; production embeds no override. - Production packaging requires the exact generated production `game.db`/manifest corpus to pass `check --all`. The external production packages and generated authority 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.