Rendezvous/docs/integration/spacegame-pilot.md

# SpaceGame consumer pilot

Tracking: Rendezvous #21 and SpaceGame #3.

The current SpaceGame checkpoint proves that the v1 client boundary establishes
authenticated direct LiteNetLib traffic without taking ownership of the game's
protocol, admission, player identity, entity identity, capacity, lifecycle, or
gameplay payloads. Real Godot processes, reconnect, an explicit dedicated
fallback, and a fresh Linux export now pass. The public package restore and a
representative external NAT/CGNAT canary remain required before #21 can close.

## Pinned checkpoint

| Input | Value |
| --- | --- |
| Rendezvous compatibility source | `ebb5eb617c0bbb170418afab396b68584b7f992e` plus the current #21 configuration/evidence changes |
| Rendezvous package source | `07004cd75fe172aa5dfdb3edda22fc280a4c4477` |
| SpaceGame source | `f3f5bc29810c362656cd7143bec1ddc2cfaf9f22` |
| Client package | `FinalFactory.Rendezvous.Client` `1.0.0` |
| Contracts package | `FinalFactory.Rendezvous.Contracts` `1.0.0` |
| LiteNetLib | `2.1.4` |
| HTTP, UDP, ticket contracts | `1` |
| SpaceGame gameplay protocol | `2` |

At the checkpoint date, the Final Factory Gitea NuGet service was reachable but
both `FinalFactory.Rendezvous.*` `1.0.0` registrations returned HTTP 404. The run
therefore restored locally built candidate packages with the hashes recorded in
[`spacegame.json`](../evidence/consumers/spacegame.json). This proves candidate
compatibility, not immutable registry publication. The release package restore
must be repeated from the public feed.

## Proven local path

The SpaceGame host and client each create one caller-owned `NetManager`, set its
three gameplay QoS channels before `Start`, and give the same manager and
`RendezvousNetListener` to the coordinator. Rendezvous authenticates discovery,
join authorization, host presence, mediation, and connection outcome reporting.
After traversal, SpaceGame performs a separate audience-bound admission exchange
on its own reliable command channel. A trusted game-auth boundary mints the
opaque assertion; the player process never receives the signing key.

The authoritative host rejects expired, replayed, incorrectly signed,
wrong-listing, duplicate-player, over-capacity, identity-mismatched,
out-of-sequence, and over-rate traffic. It assigns a canonical game entity ID
only after admission. The player ID, entity ID, listing ID, join-attempt ID, and
LiteNetLib peer ID remain distinct values.

The bounded real-process harnesses observed:

- host publication and lease maintenance;
- browser compatibility filtering and join authorization;
- typed traversal outcome `Connected`;
- successful audience-bound game admission;
- reliable ordered frame-definition and spawn lifecycle records, reliable
  ordered input, and sequenced state snapshots on the caller-owned gameplay
  socket;
- disconnect and a new authenticated session for the same durable player while
  LiteNetLib peers and canonical entity IDs change;
- immediate host lease renewal and successful host deregistration;
- a fresh optimized Linux export running the host and client in distinct
  hardened container namespaces; and
- a forced punch timeout that connects the isolated client to an explicitly
  advertised, non-loopback Docker-gateway fallback and repeats game admission.

Rendezvous exposes no gameplay relay API; all lifecycle, command, and snapshot
bytes are sent by SpaceGame through its caller-owned `NetManager`. Both Debug
and Release builds passed. Both Debug and Release test runs passed 31 tests with
zero failures. ExportRelease is optimized with debug symbols removed. The
focused formatter, shell checker, fresh-export provenance gate, clean
candidate-package restore, and adversarial branch review also passed.

## Failure evidence

| Path | Evidence | Status |
| --- | --- | --- |
| Incompatible protocol | protocol `999` returns no compatible listing and starts no traversal | Proven |
| Stale/no host presence | typed `NoHostPresence/RendezvousService/HostPresence/Mediation` | Proven |
| Traversal timeout | non-listening mediator produces typed `PunchTimedOut/LocalTraversal/NatTraversal/NatTraversal` | Proven |
| Rejected game admission | invalid signature denies gameplay in the process matrix; wrong audience, expiry, and replay are regression-tested | Proven |
| Capacity and duplicate player | game-owned roster rejects both and publishes current capacity | Regression-tested |
| Configured fallback | typed `PunchTimedOut`, explicit non-loopback endpoint, same game admission, direct gameplay | Proven locally and across Linux namespaces |
| Disconnect | host observes zero active players and final admitted count zero | Proven |
| Reconnect | same durable player enters a second authenticated session with new peer/entity IDs | Proven |

## Rendezvous-side compatibility fixes

The pilot found generic integration gaps and keeps their fixes in this
repository:

- the local production-shaped smoke tenant accepts SpaceGame gameplay protocol
  `2` and the bounded `mode` metadata key;
- the Compose smoke tenant explicitly allows its private-network service name
  and enables only the dedicated-endpoint fallback policy;
- SDK guidance requires games using multiple LiteNetLib QoS channels to set
  `ChannelsCount` before `Start` and states that Rendezvous reserves no gameplay
  channel; and
- the local credential helper rejects any signing-key file with group or other
  permissions, in addition to its ownership, symlink, and hard-link checks.

Documentation contract tests cover these generic requirements.

## Remaining acceptance gates

Do not mark #21 passed until both remaining external gates have direct evidence:

1. restore the exact immutable `1.0.0` packages from the public Gitea feed; and
2. run representative external NAT/CGNAT canaries and record the network
   topology and typed outcome.

SpaceGame #3 remains open independently for the production ENet replacement,
64/128-player profiles, and SIGTERM/drain/save evidence. The consumer pilot
does not claim those broader game-migration gates.