02 · Invitation import, discovery and first connection

Starting state

Joiner idle; receives QR or clipboard invitation through native UI. Organizer admission remains open.

Ordered events

1. Invitation → Engine

   Native scan/paste passes invitation directly

2. Engine → Engine

   Validate version, organizer key hash, ride ID and token lengths

3. Engine → Aware

   Start matching namespace discovery

4. Aware → Engine

   discovered callback supplies opaque handle and signed advertisement

5. Engine → Aware

   Select desired peer handle for an initiator request

Fields and messages

Invitation prefix and v=2; discovered peerHandle/advertisement; desiredParent differs from activeParent.

Authorization and invariants

Invitation is out-of-band trust. Verify advertisement signature/tag and monotonic serial; discovery does not grant membership or media authority.

Timers

Discovery fresh 6 s; root pulse fresh 4.5 s; request establishment budget 25 s.

Resource lifetime

Imported ride data lives until leave. Peer handles belong to the current discovery session and may change.

What the rider sees

Joining progress identifies discovery/connection/approval stages; secrets never enter React Native snapshot.

Failure branches

v1 produces update/new-invitation guidance; invalid import preserves prior state; stale/cyclic advertisements are ignored.

Resulting state

Joiner is joining; validated invitation trust and a discovered desired peer are retained.

Evidence boundary

Host invitation/discovery tests; instrumentation invitation tests compile, execution limited by current emulator environment.