# ADR 0002: publisher trust, discovery, compatibility, and fallback

- Status: Accepted
- Date: 2026-07-16
- Tracking: #2

## Context

Dedicated servers can protect provisioned credentials. Public game binaries
cannot. Discovery also needs rules that prevent accidental cross-game joins and
make the meaning of a successful authorization precise.

## Decision

### Publisher trust modes

Each `GameId` and `EnvironmentId` is provisioned policy, never caller-created
free text. V1 supports two visibly distinct publisher modes:

1. **Managed dedicated host.** A provisioned workload principal authenticates
   with a rotatable credential held outside the game binary. It is scoped to
   allowed games, environments, regions, and listing limits. Public or unlisted
   discovery may be enabled by policy.
2. **Player-hosted session.** A short-lived publisher grant is minted by a
   game-owned backend and is scoped to one game, environment, host, and expiry.
   Rendezvous does not interpret it as player identity. If a game has no grant
   issuer, it may opt into anonymous unlisted hosting with strict address and
   concurrency limits; anonymous sessions can be joined only through an opaque
   share code and never appear in public browsing.

A reusable credential embedded in a downloadable client is not authentication
and is rejected as a provisioning design. Responses and metrics expose the
publisher trust mode so operators and games can apply different policy without
claiming anonymous hosts are authenticated identities.

### Discovery and metadata

- `Public` listings can appear only in tenant-scoped compatible browsing.
- `Unlisted` listings never appear in browse results and require a random,
  unguessable share code. Unlisted does not mean private; join authorization and
  host admission still apply.
- Browser responses contain display data only. They exclude raw endpoints,
  internal IDs, lease credentials, punch capabilities, and connection tickets.
- Metadata is treated as hostile data. It is schema/budget validated, stored and
  returned as data, and never rendered as markup by the SDK or TestClient.

### Compatibility and address families

- `NetworkProtocolVersion` must match exactly in v1. `BuildVersion` is bounded
  display/diagnostic text and never overrides protocol compatibility.
- `GameId` and `EnvironmentId` must match exactly. Region is a browse filter and
  preference, not a compatibility escape hatch.
- IPv4 direct connection and NAT punching are required for v1.
- Contracts carry an address-family discriminator. IPv6 direct connections may
  use observed global IPv6 endpoints when both peers support them, but IPv6 NAT
  traversal is not a v1 release requirement.
- Public candidates are derived only from the authenticated UDP packet's source.
  For same-LAN attempts, that packet may additionally claim at most one private
  unicast candidate per supported address family. A local claim is scoped to the
  capability and is introduced only to the opposite role in the same authorized
  attempt after both roles contribute. Loopback, link-local, multicast,
  unspecified, documentation, and otherwise invalid destinations are rejected.
  The SDK bounds probes per introduced candidate and lets callers disable local
  candidates. HTTP-supplied endpoint claims are never introduced.

### Authorization and fallback

Join authorization means only that Rendezvous permits a scoped connection
attempt. It does not reserve a game slot and does not authenticate a player to
the game. The host validates and consumes the connection ticket, then applies
its own capacity, ban, identity, and gameplay rules.

The SDK returns a typed outcome including success, cancellation, timeout,
incompatibility, stale host, service rejection, host rejection, and transport
failure. A game may provision an optional dedicated fallback endpoint. The SDK
reports it but never connects without an explicit caller decision.

Gameplay relay is not part of v1. It remains a separate future service whose
need is evaluated from privacy-safe measured direct-connection failures.

## Consequences

- A player-hosted game needs a game-owned grant issuer for public discovery.
- Anonymous player hosting is useful for direct invitations but makes no user
  identity claim and receives the strictest quotas.
- Games remain responsible for presenting unsafe user-authored text safely.
- The exact-match v1 rule favors predictable interoperation over flexible
  version ranges; a later compatibility scheme must be versioned explicitly.