feat(client): standardize connection outcomes (#13)

src/FinalFactory.Rendezvous.Client/ConnectionOutcomes/RendezvousConnectionOutcome.cs

@@ -0,0 +1,183 @@
+using FinalFactory.Rendezvous.Contracts;
+using LiteNetLib;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public enum RendezvousConnectionOutcomeSource
+{
+    RendezvousService = 1,
+    LocalTraversal = 2,
+    RemoteHost = 3,
+    Caller = 4,
+    Lifecycle = 5,
+}
+
+public enum RendezvousConnectionFailureCategory
+{
+    None = 0,
+    Directory = 1,
+    Compatibility = 2,
+    Authorization = 3,
+    Capacity = 4,
+    HostPresence = 5,
+    Service = 6,
+    Mediation = 7,
+    NatTraversal = 8,
+    DirectConnection = 9,
+    Lifecycle = 10,
+}
+
+public enum RendezvousConnectionPhase
+{
+    Directory = 1,
+    Authorization = 2,
+    Mediation = 3,
+    NatTraversal = 4,
+    DirectConnection = 5,
+    Complete = 6,
+}
+
+public sealed class RendezvousConnectionOutcome
+{
+    private readonly NetworkEndpoint? _dedicatedFallback;
+
+    private RendezvousConnectionOutcome(
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
+        TimeSpan elapsed,
+        RendezvousErrorCode? serviceError,
+        NetworkEndpoint? dedicatedFallback,
+        NetPeer? peer)
+    {
+        if (elapsed < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(elapsed));
+        }
+
+        if (dedicatedFallback is not null
+            && !ContractValidation.IsNetworkEndpointValid(dedicatedFallback))
+        {
+            throw new ArgumentException("The dedicated fallback endpoint is invalid.", nameof(dedicatedFallback));
+        }
+
+        Kind = kind;
+        Source = source;
+        Category = category;
+        Phase = phase;
+        Elapsed = elapsed;
+        ServiceError = serviceError;
+        _dedicatedFallback = RendezvousEndpoint.Copy(dedicatedFallback);
+        Peer = peer;
+    }
+
+    public ConnectionOutcomeKind Kind { get; }
+    public RendezvousConnectionOutcomeSource Source { get; }
+    public RendezvousConnectionFailureCategory Category { get; }
+    public RendezvousConnectionPhase Phase { get; }
+    public TimeSpan Elapsed { get; }
+    public RendezvousErrorCode? ServiceError { get; }
+    public NetworkEndpoint? DedicatedFallback => RendezvousEndpoint.Copy(_dedicatedFallback);
+    public NetPeer? Peer { get; }
+    public bool IsSuccess => Kind == ConnectionOutcomeKind.Connected;
+    public bool HasDedicatedFallback => _dedicatedFallback is not null;
+
+    public static RendezvousConnectionOutcome FromServiceError(
+        RendezvousErrorCode error,
+        TimeSpan elapsed,
+        NetworkEndpoint? dedicatedFallback = null)
+    {
+        if (error == RendezvousErrorCode.None)
+        {
+            throw new ArgumentException("A service failure outcome requires an error.", nameof(error));
+        }
+
+        (ConnectionOutcomeKind kind, RendezvousConnectionFailureCategory category, RendezvousConnectionPhase phase) =
+            error switch
+            {
+                RendezvousErrorCode.NotFound => (
+                    ConnectionOutcomeKind.DirectoryNotFound,
+                    RendezvousConnectionFailureCategory.Directory,
+                    RendezvousConnectionPhase.Directory),
+                RendezvousErrorCode.Expired => (
+                    ConnectionOutcomeKind.AttemptExpired,
+                    RendezvousConnectionFailureCategory.Authorization,
+                    RendezvousConnectionPhase.Authorization),
+                RendezvousErrorCode.IncompatibleProtocol => (
+                    ConnectionOutcomeKind.IncompatibleProtocol,
+                    RendezvousConnectionFailureCategory.Compatibility,
+                    RendezvousConnectionPhase.Directory),
+                RendezvousErrorCode.AuthenticationRequired
+                    or RendezvousErrorCode.Forbidden
+                    or RendezvousErrorCode.ReplayRejected => (
+                        ConnectionOutcomeKind.Unauthorized,
+                        RendezvousConnectionFailureCategory.Authorization,
+                        RendezvousConnectionPhase.Authorization),
+                RendezvousErrorCode.RateLimited
+                    or RendezvousErrorCode.CapacityExceeded => (
+                        ConnectionOutcomeKind.RateLimited,
+                        RendezvousConnectionFailureCategory.Capacity,
+                        RendezvousConnectionPhase.Authorization),
+                RendezvousErrorCode.StaleHost => (
+                    ConnectionOutcomeKind.NoHostPresence,
+                    RendezvousConnectionFailureCategory.HostPresence,
+                    RendezvousConnectionPhase.Mediation),
+                RendezvousErrorCode.ServiceUnavailable => (
+                    ConnectionOutcomeKind.ServiceUnavailable,
+                    RendezvousConnectionFailureCategory.Service,
+                    RendezvousConnectionPhase.Authorization),
+                _ => (
+                    ConnectionOutcomeKind.ServiceRejected,
+                    RendezvousConnectionFailureCategory.Service,
+                    RendezvousConnectionPhase.Authorization),
+            };
+        return new(
+            kind,
+            RendezvousConnectionOutcomeSource.RendezvousService,
+            category,
+            phase,
+            elapsed,
+            error,
+            dedicatedFallback,
+            null);
+    }
+
+    public static ConnectionElapsedBucket BucketElapsed(TimeSpan elapsed)
+    {
+        if (elapsed < TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(nameof(elapsed));
+        }
+
+        return elapsed.TotalSeconds switch
+        {
+            < 1 => ConnectionElapsedBucket.UnderOneSecond,
+            < 5 => ConnectionElapsedBucket.OneToFiveSeconds,
+            < 15 => ConnectionElapsedBucket.FiveToFifteenSeconds,
+            < 30 => ConnectionElapsedBucket.FifteenToThirtySeconds,
+            _ => ConnectionElapsedBucket.ThirtySecondsOrMore,
+        };
+    }
+
+    public override string ToString() =>
+        $"[RendezvousConnectionOutcome {Kind}; {Source}; credentials redacted]";
+
+    internal static RendezvousConnectionOutcome Create(
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
+        TimeSpan elapsed,
+        NetworkEndpoint? dedicatedFallback = null,
+        NetPeer? peer = null) => new(
+            kind,
+            source,
+            category,
+            phase,
+            elapsed,
+            null,
+            dedicatedFallback,
+            peer);
+
+}

src/FinalFactory.Rendezvous.Client/ConnectionOutcomes/RendezvousConnectionStartResult.cs

@@ -0,0 +1,35 @@
+using FinalFactory.Rendezvous.Contracts;
+
+namespace FinalFactory.Rendezvous.Client;
+
+public sealed class RendezvousConnectionStartResult
+{
+    internal RendezvousConnectionStartResult(
+        CreateJoinAttemptResponse? attempt,
+        RendezvousConnectionOutcome? outcome)
+    {
+        if ((attempt is null) == (outcome is null))
+        {
+            throw new ArgumentException(
+                "A connection start result requires exactly one attempt or terminal outcome.");
+        }
+
+        Attempt = attempt;
+        Outcome = outcome;
+    }
+
+    public CreateJoinAttemptResponse? Attempt { get; }
+    public RendezvousConnectionOutcome? Outcome { get; }
+    public bool IsReadyForTraversal => Attempt is not null;
+    public bool IsCompleted => Outcome is not null;
+
+    public static RendezvousConnectionStartResult ReadyForTraversal(
+        CreateJoinAttemptResponse attempt) => new(
+        attempt ?? throw new ArgumentNullException(nameof(attempt)),
+        null);
+
+    public static RendezvousConnectionStartResult Completed(
+        RendezvousConnectionOutcome outcome) => new(
+        null,
+        outcome ?? throw new ArgumentNullException(nameof(outcome)));
+}

src/FinalFactory.Rendezvous.Client/JoinAttempts/RendezvousJoinClient.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using FinalFactory.Rendezvous.Contracts;
 
 namespace FinalFactory.Rendezvous.Client;
@@ -39,6 +40,45 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
             cancellationToken);
     }
 
+    public async Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+        CreateJoinAttemptRequest request,
+        NetworkEndpoint? dedicatedFallback = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (dedicatedFallback is not null
+            && !ContractValidation.IsNetworkEndpointValid(dedicatedFallback))
+        {
+            throw new ArgumentException("The dedicated fallback endpoint is invalid.", nameof(dedicatedFallback));
+        }
+
+        Stopwatch elapsed = Stopwatch.StartNew();
+        try
+        {
+            RendezvousClientResult<CreateJoinAttemptResponse> result = await CreateAsync(
+                request,
+                cancellationToken).ConfigureAwait(false);
+            elapsed.Stop();
+            return result.IsSuccess && result.Value is not null
+                ? RendezvousConnectionStartResult.ReadyForTraversal(result.Value)
+                : RendezvousConnectionStartResult.Completed(
+                    RendezvousConnectionOutcome.FromServiceError(
+                        result.Error,
+                        elapsed.Elapsed,
+                        dedicatedFallback));
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            elapsed.Stop();
+            return RendezvousConnectionStartResult.Completed(
+                RendezvousConnectionOutcome.Create(
+                    ConnectionOutcomeKind.Cancelled,
+                    RendezvousConnectionOutcomeSource.Caller,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    RendezvousConnectionPhase.Authorization,
+                    elapsed.Elapsed));
+        }
+    }
+
     public Task<RendezvousClientResult<bool>> CancelAsync(
         CreateJoinAttemptResponse attempt,
         CancellationToken cancellationToken = default)
@@ -130,6 +170,41 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
             $"Host invitation polling exceeded the configured {maximumPages}-page limit.");
     }
 
+    public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+        CreateJoinAttemptResponse attempt,
+        RendezvousConnectionOutcome outcome,
+        CancellationToken cancellationToken = default)
+    {
+        if (attempt is null)
+        {
+            throw new ArgumentNullException(nameof(attempt));
+        }
+        if (outcome is null)
+        {
+            throw new ArgumentNullException(nameof(outcome));
+        }
+        if (!ContractValidation.IsReportableConnectionOutcome(outcome.Kind))
+        {
+            throw new ArgumentException(
+                "This outcome cannot be reported for an issued join attempt.",
+                nameof(outcome));
+        }
+
+        ReportConnectionOutcomeRequest body = new()
+        {
+            Outcome = outcome.Kind,
+            ElapsedBucket = RendezvousConnectionOutcome.BucketElapsed(outcome.Elapsed),
+        };
+        return _transport.SendSafeAsync<ReportConnectionOutcomeResponse>(
+            () => HeaderJsonRequest(
+                HttpMethod.Post,
+                $"v1/join-attempts/{attempt.AttemptId}/outcome",
+                ClientPunchCapabilityHeader,
+                RequireHeaderValue(attempt.ClientPunchCapability, nameof(attempt)),
+                body),
+            cancellationToken);
+    }
+
     private static HttpRequestMessage HeaderRequest(
         HttpMethod method,
         string uri,
@@ -141,6 +216,18 @@ public sealed class RendezvousJoinClient : IRendezvousJoinClient
         return request;
     }
 
+    private static HttpRequestMessage HeaderJsonRequest<T>(
+        HttpMethod method,
+        string uri,
+        string header,
+        string value,
+        T body)
+    {
+        HttpRequestMessage request = RendezvousHttpTransport.JsonRequest(method, uri, body);
+        request.Headers.TryAddWithoutValidation(header, value);
+        return request;
+    }
+
     private static string RequireHeaderValue(string value, string parameterName) =>
         !string.IsNullOrWhiteSpace(value)
             ? value

src/FinalFactory.Rendezvous.Client/README.md

@@ -29,6 +29,12 @@ RendezvousClientResult<PublishedSession> registered = await publisher.RegisterAs
         DisplayName = "My server",
         Visibility = ListingVisibility.Public,
         Capacity = new() { CurrentPlayers = 1, MaximumPlayers = 8 },
+        DedicatedFallback = new()
+        {
+            AddressFamily = AddressFamilyKind.Ipv4,
+            Address = "203.0.113.40",
+            Port = 7777,
+        },
     },
     publisherCredential,
     cancellationToken);
@@ -97,14 +103,22 @@ the accepted peer as connected. Register ordinary gameplay callbacks on
 `networkEvents.GameplayEvents`; the routing listener reserves Rendezvous direct
 requests for ticket validation and forwards every other callback normally.
 
-The joining game first creates the HTTP attempt, then uses its own already-started
-gameplay manager in the same frame loop:
+The joining game first requests an attempt through the typed start API. It returns
+exactly one issued attempt or one terminal service outcome, so service authority
+is not confused with a later locally observed traversal failure:
 
 ```csharp
-CreateJoinAttemptResponse attempt = (await joins.CreateAsync(
+RendezvousConnectionStartResult start = await joins.CreateConnectionAttemptAsync(
     createJoinRequest,
-    cancellationToken)).Value
-    ?? throw new InvalidOperationException("Join issuance failed.");
+    cancellationToken: cancellationToken);
+if (start.Outcome is { } serviceOutcome)
+{
+    ShowConnectionFailure(serviceOutcome.Kind, serviceOutcome.Category);
+    return;
+}
+
+CreateJoinAttemptResponse attempt = start.Attempt
+    ?? throw new InvalidOperationException("The typed start result was invalid.");
 using RendezvousClientCoordinator client = new(
     gameplayNetManager,
     networkEvents,
@@ -116,12 +130,35 @@ client.Poll();
 ```
 
 NAT introduction changes the client state to `Connecting`; it is not success.
-Only `Connected` supplies `ConnectedPeer`. Call `Cancel()` and then `Poll()` for
-local cancellation, or `CancelAsync(joins, cancellationToken)` to also revoke the
-service attempt. Terminal client paths release all event subscriptions. Disposing
-a coordinator never stops or disposes the caller-owned manager and does not touch
-an in-flight peer; call `Cancel()` followed by `Poll()` first when that peer must
-also be disconnected.
+Only a `Connected` outcome supplies `Peer`. Completion exposes a stable kind,
+source, category, phase, and elapsed duration. The default HTTP silence, punch,
+and direct-connect budgets are five, ten, and five seconds respectively; configure
+them through `RendezvousClientOptions` and `RendezvousCoordinatorOptions` when a
+game has measured reasons to do so. The signed attempt expiry is always the
+absolute upper bound.
+
+Call `Cancel()` and then `Poll()` for local cancellation, or
+`CancelAsync(joins, cancellationToken)` to also revoke the service attempt.
+Terminal client paths complete exactly once and release all event subscriptions,
+so late packets and callbacks are inert. Disposing a coordinator never stops or
+disposes the caller-owned manager and does not touch an in-flight peer; call
+`Cancel()` followed by `Poll()` first when that peer must also be disconnected.
+
+After terminal completion, reporting is explicit and safe to retry. It sends only
+the authenticated outcome enum and a coarse elapsed bucket—never the endpoint,
+exact duration, diagnostic text, metadata, or player identity:
+
+```csharp
+RendezvousClientResult<ReportConnectionOutcomeResponse> report =
+    await client.ReportOutcomeAsync(joins, cancellationToken);
+```
+
+An optional `DedicatedFallback` is copied from the authoritative listing into the
+issued attempt and terminal outcome. A local deployment may replace it with
+`RendezvousCoordinatorOptions.DedicatedFallbackOverride`. The SDK only returns
+the endpoint; it never connects automatically. The game must explicitly decide
+whether to use it and then connect and authenticate through its own gameplay
+transport. If the outcome has no fallback, v1 offers no relay.
 
 Lease renewal is explicit and caller-controlled:
 
@@ -155,5 +192,6 @@ apply its own player identity, capacity, ban, and gameplay admission rules. Revo
 the attempt on cancellation and dispose the validator during host shutdown so its
 keyed ticket digests are zeroed.
 
-See the repository's ADR 0007 for HTTP ownership/retry semantics and ADR 0008 for
-join-capability and connection-ticket security semantics.
+See the repository's ADR 0007 for HTTP ownership/retry semantics, ADR 0008 for
+join-capability and connection-ticket security semantics, and ADR 0010 for typed
+outcomes, deadlines, reporting, and caller-owned fallback.

src/FinalFactory.Rendezvous.Client/RendezvousClientAbstractions.cs

@@ -148,6 +148,11 @@ public interface IRendezvousSessionBrowserClient
 
 public interface IRendezvousJoinClient
 {
+    Task<RendezvousConnectionStartResult> CreateConnectionAttemptAsync(
+        CreateJoinAttemptRequest request,
+        NetworkEndpoint? dedicatedFallback = null,
+        CancellationToken cancellationToken = default);
+
     Task<RendezvousClientResult<CreateJoinAttemptResponse>> CreateAsync(
         CreateJoinAttemptRequest request,
         CancellationToken cancellationToken = default);
@@ -166,6 +171,11 @@ public interface IRendezvousJoinClient
         PublishedSession session,
         int maximumPages = 100,
         CancellationToken cancellationToken = default);
+
+    Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+        CreateJoinAttemptResponse attempt,
+        RendezvousConnectionOutcome outcome,
+        CancellationToken cancellationToken = default);
 }
 
 public interface IRendezvousDelay
@@ -176,6 +186,7 @@ public interface IRendezvousDelay
 public sealed class RendezvousClientOptions
 {
     public int MaximumSafeRetries { get; set; } = 2;
+    public TimeSpan RequestTimeout { get; set; } = TimeSpan.FromSeconds(5);
     public TimeSpan InitialRetryDelay { get; set; } = TimeSpan.FromMilliseconds(200);
     public TimeSpan MaximumRetryDelay { get; set; } = TimeSpan.FromSeconds(2);
     public double JitterRatio { get; set; } = 0.2;
@@ -183,6 +194,8 @@ public sealed class RendezvousClientOptions
     internal void Validate()
     {
         if (MaximumSafeRetries is < 0 or > 5
+            || RequestTimeout <= TimeSpan.Zero
+            || RequestTimeout > TimeSpan.FromSeconds(30)
             || InitialRetryDelay < TimeSpan.Zero
             || MaximumRetryDelay < InitialRetryDelay
             || MaximumRetryDelay > TimeSpan.FromSeconds(30)
@@ -198,3 +211,15 @@ internal sealed class SystemRendezvousDelay : IRendezvousDelay
     public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken) =>
         Task.Delay(delay, cancellationToken);
 }
+
+internal static class RendezvousEndpoint
+{
+    internal static NetworkEndpoint? Copy(NetworkEndpoint? endpoint) => endpoint is null
+        ? null
+        : new NetworkEndpoint
+        {
+            AddressFamily = endpoint.AddressFamily,
+            Address = endpoint.Address,
+            Port = endpoint.Port,
+        };
+}

src/FinalFactory.Rendezvous.Client/RendezvousHttpTransport.cs

@@ -24,6 +24,7 @@ internal sealed class RendezvousHttpTransport
         _options = new RendezvousClientOptions
         {
             MaximumSafeRetries = suppliedOptions.MaximumSafeRetries,
+            RequestTimeout = suppliedOptions.RequestTimeout,
             InitialRetryDelay = suppliedOptions.InitialRetryDelay,
             MaximumRetryDelay = suppliedOptions.MaximumRetryDelay,
             JitterRatio = suppliedOptions.JitterRatio,
@@ -38,11 +39,15 @@ internal sealed class RendezvousHttpTransport
         for (int attempt = 0; ; attempt++)
         {
             cancellationToken.ThrowIfCancellationRequested();
+            using CancellationTokenSource requestTimeout =
+                CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            requestTimeout.CancelAfter(_options.RequestTimeout);
+            CancellationToken requestCancellation = requestTimeout.Token;
             try
             {
                 using HttpRequestMessage request = requestFactory();
                 using HttpResponseMessage response = await _httpClient
-                    .SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken)
+                    .SendAsync(request, HttpCompletionOption.ResponseHeadersRead, requestCancellation)
                     .ConfigureAwait(false);
                 if (response.IsSuccessStatusCode)
                 {
@@ -54,7 +59,7 @@ internal sealed class RendezvousHttpTransport
                     byte[] payload;
                     try
                     {
-                        payload = await ReadBoundedAsync(response.Content, cancellationToken)
+                        payload = await ReadBoundedAsync(response.Content, requestCancellation)
                             .ConfigureAwait(false);
                     }
                     catch (InvalidDataException)
@@ -81,7 +86,7 @@ internal sealed class RendezvousHttpTransport
                         : RendezvousClientResult.Success(value);
                 }
 
-                ApiError error = await ReadErrorAsync(response, cancellationToken).ConfigureAwait(false);
+                ApiError error = await ReadErrorAsync(response, requestCancellation).ConfigureAwait(false);
                 int? retryAfter = error.RetryAfterSeconds ?? GetRetryAfterSeconds(response.Headers.RetryAfter);
                 if (attempt < _options.MaximumSafeRetries && IsTransient(error.Code))
                 {

src/FinalFactory.Rendezvous.Client/RendezvousPublisherClient.cs

@@ -88,6 +88,7 @@ public sealed class RendezvousPublisherClient : IRendezvousPublisherClient
             DisplayName = request.DisplayName,
             Capacity = CopyCapacity(request.Capacity),
             Metadata = CopyMetadata(request.Metadata),
+            DedicatedFallback = RendezvousEndpoint.Copy(request.DedicatedFallback),
         };
         return _transport.SendSafeAsync<bool>(
             () => RendezvousHttpTransport.JsonRequest(
@@ -138,6 +139,7 @@ public sealed class RendezvousPublisherClient : IRendezvousPublisherClient
         Visibility = request.Visibility,
         Capacity = CopyCapacity(request.Capacity),
         Metadata = CopyMetadata(request.Metadata),
+        DedicatedFallback = RendezvousEndpoint.Copy(request.DedicatedFallback),
     };
 
     private static SessionCapacity CopyCapacity(SessionCapacity capacity) => new()
@@ -148,4 +150,5 @@ public sealed class RendezvousPublisherClient : IRendezvousPublisherClient
 
     private static Dictionary<string, string> CopyMetadata(Dictionary<string, string> metadata) =>
         new(metadata, StringComparer.Ordinal);
+
 }

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousClientCoordinator.cs

@@ -1,4 +1,5 @@
 using System.Net;
+using System.Net.Sockets;
 using FinalFactory.Rendezvous.Contracts;
 using LiteNetLib;
 
@@ -12,12 +13,21 @@ public sealed class RendezvousClientCoordinator : IDisposable
     private readonly IPEndPoint _mediator;
     private readonly CreateJoinAttemptResponse _attempt;
     private readonly IRendezvousCoordinatorClock _clock;
+    private readonly RendezvousCoordinatorOptions _options;
     private readonly RendezvousPunchRetrySchedule _retry;
+    private readonly object _completionGate = new();
+    private readonly TimeSpan _startedAt;
+    private readonly TimeSpan _attemptDeadline;
+    private readonly TimeSpan _punchDeadline;
+    private readonly NetworkEndpoint? _dedicatedFallback;
     private NetPeer? _connectingPeer;
+    private IPEndPoint? _directEndpoint;
+    private TimeSpan? _directDeadline;
+    private RendezvousConnectionOutcome? _outcome;
     private bool _cancelRequested;
     private int _polling;
     private bool _subscriptionsReleased;
-    private bool _disposed;
+    private int _disposed;
 
     public RendezvousClientCoordinator(
         NetManager manager,
@@ -49,23 +59,31 @@ public sealed class RendezvousClientCoordinator : IDisposable
         _mediator = mediator ?? throw new ArgumentNullException(nameof(mediator));
         _attempt = attempt ?? throw new ArgumentNullException(nameof(attempt));
         _clock = clock ?? throw new ArgumentNullException(nameof(clock));
-        RendezvousCoordinatorOptions validated = (options ?? new RendezvousCoordinatorOptions())
+        _options = (options ?? new RendezvousCoordinatorOptions())
             .CopyAndValidate();
-        _retry = new(validated, _clock);
+        _retry = new(_options, _clock);
 
         RendezvousManagerGuard.Validate(_manager, _networkEvents);
+        DateTimeOffset startedUtc = _clock.UtcNow;
         if (_mediator.Port is < 1 or > 65_535
             || _attempt.AttemptId.Value == Guid.Empty
             || _attempt.MediationHandle.Value == Guid.Empty
             || !ContractValidation.IsCapabilityValid(_attempt.ClientPunchCapability)
             || !ContractValidation.IsConnectionTicketValid(_attempt.ConnectionTicketDigest)
-            || _attempt.ExpiresAt <= _clock.UtcNow)
+            || _attempt.ExpiresAt <= startedUtc)
         {
             throw new ArgumentException("The client traversal inputs are invalid.");
         }
 
+        _startedAt = _clock.Elapsed;
+        _attemptDeadline = _startedAt + (_attempt.ExpiresAt - startedUtc);
+        _punchDeadline = Min(_attemptDeadline, _startedAt + _options.PunchTimeout);
+        _dedicatedFallback = RendezvousEndpoint.Copy(
+            _options.DedicatedFallbackOverride ?? _attempt.DedicatedFallback);
+
         _networkEvents.RendezvousPeerConnected += OnPeerConnected;
         _networkEvents.RendezvousPeerDisconnected += OnPeerDisconnected;
+        _networkEvents.RendezvousNetworkError += OnNetworkError;
         _punchEvents.NatIntroductionSuccess += OnNatIntroductionSuccess;
     }
 
@@ -73,7 +91,8 @@ public sealed class RendezvousClientCoordinator : IDisposable
 
     public RendezvousConnectionState State { get; private set; } = RendezvousConnectionState.Punching;
     public NetPeer? ConnectedPeer { get; private set; }
-    public bool IsCompleted => IsTerminal(State);
+    public RendezvousConnectionOutcome? Outcome => Volatile.Read(ref _outcome);
+    public bool IsCompleted => Outcome is not null;
 
     public void Cancel() => Volatile.Write(ref _cancelRequested, true);
 
@@ -91,6 +110,23 @@ public sealed class RendezvousClientCoordinator : IDisposable
         return await joinClient.CancelAsync(_attempt, cancellationToken).ConfigureAwait(false);
     }
 
+    public Task<RendezvousClientResult<ReportConnectionOutcomeResponse>> ReportOutcomeAsync(
+        IRendezvousJoinClient joinClient,
+        CancellationToken cancellationToken = default)
+    {
+        if (joinClient is null)
+        {
+            throw new ArgumentNullException(nameof(joinClient));
+        }
+        ThrowIfDisposed();
+        if (Outcome is null)
+        {
+            throw new InvalidOperationException("The connection attempt has not completed.");
+        }
+
+        return joinClient.ReportOutcomeAsync(_attempt, Outcome, cancellationToken);
+    }
+
     public void Poll()
     {
         ThrowIfDisposed();
@@ -109,13 +145,18 @@ public sealed class RendezvousClientCoordinator : IDisposable
             if (Volatile.Read(ref _cancelRequested))
             {
                 DisconnectPendingPeer();
-                Complete(RendezvousConnectionState.Cancelled);
+                Complete(
+                    RendezvousConnectionState.Cancelled,
+                    ConnectionOutcomeKind.Cancelled,
+                    RendezvousConnectionOutcomeSource.Caller,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    CurrentPhase());
                 return;
             }
 
             if (!_manager.IsRunning)
             {
-                Complete(RendezvousConnectionState.ManagerStopped);
+                CompleteManagerStopped();
                 return;
             }
 
@@ -127,35 +168,67 @@ public sealed class RendezvousClientCoordinator : IDisposable
             }
 
             DateTimeOffset now = _clock.UtcNow;
+            TimeSpan elapsed = _clock.Elapsed;
             if (Volatile.Read(ref _cancelRequested))
             {
                 DisconnectPendingPeer();
-                Complete(RendezvousConnectionState.Cancelled);
+                Complete(
+                    RendezvousConnectionState.Cancelled,
+                    ConnectionOutcomeKind.Cancelled,
+                    RendezvousConnectionOutcomeSource.Caller,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    CurrentPhase());
             }
             else if (!_manager.IsRunning)
             {
-                Complete(RendezvousConnectionState.ManagerStopped);
+                CompleteManagerStopped();
             }
-            else if (now >= _attempt.ExpiresAt)
+            else if (now >= _attempt.ExpiresAt || elapsed >= _attemptDeadline)
             {
                 DisconnectPendingPeer();
-                Complete(RendezvousConnectionState.TimedOut);
+                Complete(
+                    RendezvousConnectionState.TimedOut,
+                    ConnectionOutcomeKind.AttemptExpired,
+                    RendezvousConnectionOutcomeSource.RendezvousService,
+                    RendezvousConnectionFailureCategory.Authorization,
+                    RendezvousConnectionPhase.Authorization);
             }
-            else if (State == RendezvousConnectionState.Punching && _retry.IsDue(now))
+            else if (State == RendezvousConnectionState.Punching)
             {
-                if (_retry.IsExhausted)
+                if (elapsed >= _punchDeadline
+                    || _retry.IsExhausted && _retry.IsDue(elapsed))
                 {
-                    Complete(RendezvousConnectionState.TimedOut);
+                    Complete(
+                        RendezvousConnectionState.TimedOut,
+                        ConnectionOutcomeKind.PunchTimedOut,
+                        RendezvousConnectionOutcomeSource.LocalTraversal,
+                        RendezvousConnectionFailureCategory.NatTraversal,
+                        RendezvousConnectionPhase.NatTraversal);
                     return;
                 }
 
-                _manager.NatPunchModule.SendNatIntroduceRequest(
-                    _mediator,
-                    NatPunchRequestTokenCodec.Encode(
-                        NatPunchPeerRole.Client,
-                        _attempt.MediationHandle,
-                        _attempt.ClientPunchCapability));
-                _retry.RecordRequest();
+                if (_retry.IsDue(elapsed))
+                {
+                    _manager.NatPunchModule.SendNatIntroduceRequest(
+                        _mediator,
+                        NatPunchRequestTokenCodec.Encode(
+                            NatPunchPeerRole.Client,
+                            _attempt.MediationHandle,
+                            _attempt.ClientPunchCapability));
+                    _retry.RecordRequest();
+                }
+            }
+            else if (State == RendezvousConnectionState.Connecting
+                && _directDeadline is TimeSpan directDeadline
+                && directDeadline <= elapsed)
+            {
+                DisconnectPendingPeer();
+                Complete(
+                    RendezvousConnectionState.TimedOut,
+                    ConnectionOutcomeKind.DirectConnectTimedOut,
+                    RendezvousConnectionOutcomeSource.LocalTraversal,
+                    RendezvousConnectionFailureCategory.DirectConnection,
+                    RendezvousConnectionPhase.DirectConnection);
             }
         }
         finally
@@ -166,18 +239,22 @@ public sealed class RendezvousClientCoordinator : IDisposable
 
     public void Dispose()
     {
-        if (_disposed)
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
         {
             return;
         }
 
         if (!IsCompleted)
         {
-            Complete(RendezvousConnectionState.Disposed);
+            Complete(
+                RendezvousConnectionState.Disposed,
+                ConnectionOutcomeKind.Disposed,
+                RendezvousConnectionOutcomeSource.Lifecycle,
+                RendezvousConnectionFailureCategory.Lifecycle,
+                CurrentPhase());
         }
 
         ReleaseSubscriptions();
-        _disposed = true;
     }
 
     public override string ToString() =>
@@ -205,16 +282,25 @@ public sealed class RendezvousClientCoordinator : IDisposable
         byte[] connectionData = DirectConnectionRequestCodec.Encode(
             introduction.AttemptId,
             introduction.ConnectionTicket);
+        _directEndpoint = target;
         _connectingPeer = _manager.Connect(target, connectionData);
         if (_connectingPeer is null
             || _connectingPeer.ConnectionState != ConnectionState.Outgoing)
         {
             _connectingPeer = null;
-            Complete(RendezvousConnectionState.Rejected);
+            Complete(
+                RendezvousConnectionState.Rejected,
+                ConnectionOutcomeKind.TransportError,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection);
             return;
         }
 
         State = RendezvousConnectionState.Connecting;
+        _directDeadline = Min(
+            _attemptDeadline,
+            _clock.Elapsed + _options.DirectConnectTimeout);
     }
 
     private void OnPeerConnected(NetPeer peer)
@@ -225,17 +311,60 @@ public sealed class RendezvousClientCoordinator : IDisposable
             return;
         }
 
-        ConnectedPeer = peer;
-        Complete(RendezvousConnectionState.Connected, peer);
+        Complete(
+            RendezvousConnectionState.Connected,
+            ConnectionOutcomeKind.Connected,
+            RendezvousConnectionOutcomeSource.LocalTraversal,
+            RendezvousConnectionFailureCategory.None,
+            RendezvousConnectionPhase.Complete,
+            peer);
     }
 
     private void OnPeerDisconnected(NetPeer peer, DisconnectInfo disconnectInfo)
     {
-        _ = disconnectInfo;
         if (State == RendezvousConnectionState.Connecting
             && ReferenceEquals(peer, _connectingPeer))
         {
-            Complete(RendezvousConnectionState.Rejected);
+            ConnectionOutcomeKind kind = disconnectInfo.Reason == DisconnectReason.Timeout
+                ? ConnectionOutcomeKind.DirectConnectTimedOut
+                : disconnectInfo.Reason == DisconnectReason.ConnectionFailed
+                    ? ConnectionOutcomeKind.TransportError
+                    : ConnectionOutcomeKind.HostRejected;
+            Complete(
+                kind == ConnectionOutcomeKind.DirectConnectTimedOut
+                    ? RendezvousConnectionState.TimedOut
+                    : RendezvousConnectionState.Rejected,
+                kind,
+                kind == ConnectionOutcomeKind.HostRejected
+                    ? RendezvousConnectionOutcomeSource.RemoteHost
+                    : RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection);
+        }
+    }
+
+    private void OnNetworkError(IPEndPoint endpoint, SocketError socketError)
+    {
+        _ = socketError;
+        if (State == RendezvousConnectionState.Punching && endpoint.Equals(_mediator))
+        {
+            Complete(
+                RendezvousConnectionState.Rejected,
+                ConnectionOutcomeKind.MediatorUnavailable,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.Mediation,
+                RendezvousConnectionPhase.Mediation);
+        }
+        else if (State == RendezvousConnectionState.Connecting
+            && endpoint.Equals(_directEndpoint))
+        {
+            DisconnectPendingPeer();
+            Complete(
+                RendezvousConnectionState.Rejected,
+                ConnectionOutcomeKind.TransportError,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection);
         }
     }
 
@@ -247,42 +376,85 @@ public sealed class RendezvousClientCoordinator : IDisposable
         }
     }
 
-    private void Complete(RendezvousConnectionState terminalState, NetPeer? peer = null)
+    private void Complete(
+        RendezvousConnectionState terminalState,
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
+        NetPeer? peer = null)
     {
-        if (IsCompleted)
+        RendezvousConnectionCompletedEventArgs completion;
+        lock (_completionGate)
         {
-            return;
+            if (_outcome is not null)
+            {
+                return;
+            }
+
+            RendezvousConnectionOutcome outcome = RendezvousConnectionOutcome.Create(
+                kind,
+                source,
+                category,
+                phase,
+                _clock.Elapsed - _startedAt,
+                ShouldOfferFallback(kind) ? _dedicatedFallback : null,
+                peer);
+            State = terminalState;
+            if (kind == ConnectionOutcomeKind.Connected)
+            {
+                ConnectedPeer = peer;
+            }
+            Volatile.Write(ref _outcome, outcome);
+            ReleaseSubscriptions();
+            completion = new(terminalState, outcome);
         }
 
-        State = terminalState;
-        ReleaseSubscriptions();
-        Completed?.Invoke(this, new(terminalState, peer));
+        Completed?.Invoke(this, completion);
     }
 
     private void ReleaseSubscriptions()
     {
-        if (_subscriptionsReleased)
+        lock (_completionGate)
         {
-            return;
-        }
+            if (_subscriptionsReleased)
+            {
+                return;
+            }
 
-        _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
-        _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
-        _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
-        _subscriptionsReleased = true;
+            _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
+            _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
+            _networkEvents.RendezvousNetworkError -= OnNetworkError;
+            _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
+            _subscriptionsReleased = true;
+        }
     }
 
-    private static bool IsTerminal(RendezvousConnectionState state) => state is
-        RendezvousConnectionState.Connected
-        or RendezvousConnectionState.Cancelled
-        or RendezvousConnectionState.TimedOut
-        or RendezvousConnectionState.Rejected
-        or RendezvousConnectionState.ManagerStopped
-        or RendezvousConnectionState.Disposed;
+    private void CompleteManagerStopped() => Complete(
+        RendezvousConnectionState.ManagerStopped,
+        ConnectionOutcomeKind.ManagerStopped,
+        RendezvousConnectionOutcomeSource.Lifecycle,
+        RendezvousConnectionFailureCategory.Lifecycle,
+        CurrentPhase());
+
+    private RendezvousConnectionPhase CurrentPhase() => State switch
+    {
+        RendezvousConnectionState.Punching => RendezvousConnectionPhase.NatTraversal,
+        RendezvousConnectionState.Connecting => RendezvousConnectionPhase.DirectConnection,
+        _ => RendezvousConnectionPhase.Complete,
+    };
+
+    private static bool ShouldOfferFallback(ConnectionOutcomeKind kind) => kind is not (
+        ConnectionOutcomeKind.Connected
+        or ConnectionOutcomeKind.Cancelled
+        or ConnectionOutcomeKind.Disposed);
+
+    private static TimeSpan Min(TimeSpan left, TimeSpan right) =>
+        left <= right ? left : right;
 
     private void ThrowIfDisposed()
     {
-        if (_disposed)
+        if (Volatile.Read(ref _disposed) != 0)
         {
             throw new ObjectDisposedException(nameof(RendezvousClientCoordinator));
         }

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousCoordinatorAbstractions.cs

@@ -1,4 +1,6 @@
+using System.Diagnostics;
 using System.Security.Cryptography;
+using FinalFactory.Rendezvous.Contracts;
 using LiteNetLib;
 
 namespace FinalFactory.Rendezvous.Client;
@@ -15,12 +17,97 @@ public enum RendezvousConnectionState
     Disposed = 8,
 }
 
-public sealed class RendezvousConnectionCompletedEventArgs(
-    RendezvousConnectionState state,
-    NetPeer? peer = null) : EventArgs
+public sealed class RendezvousConnectionCompletedEventArgs : EventArgs
 {
-    public RendezvousConnectionState State { get; } = state;
-    public NetPeer? Peer { get; } = peer;
+    [Obsolete("Completion events now expose a typed Outcome. Construct these arguments only for legacy test doubles.")]
+    public RendezvousConnectionCompletedEventArgs(
+        RendezvousConnectionState state,
+        NetPeer? peer)
+        : this(state, RendezvousCompletionInvariant.FromLegacy(state, peer))
+    {
+    }
+
+    internal RendezvousConnectionCompletedEventArgs(
+        RendezvousConnectionState state,
+        RendezvousConnectionOutcome outcome)
+    {
+        RendezvousCompletionInvariant.Validate(state, outcome);
+        State = state;
+        Outcome = outcome;
+    }
+
+    public RendezvousConnectionState State { get; }
+    public RendezvousConnectionOutcome Outcome { get; }
+    public NetPeer? Peer => Outcome.Peer;
+}
+
+internal static class RendezvousCompletionInvariant
+{
+    internal static RendezvousConnectionOutcome FromLegacy(
+        RendezvousConnectionState state,
+        NetPeer? peer) => state switch
+        {
+            RendezvousConnectionState.Connected when peer is not null => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.Connected,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.None,
+                RendezvousConnectionPhase.Complete,
+                TimeSpan.Zero,
+                peer: peer),
+            RendezvousConnectionState.Cancelled => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.Cancelled,
+                RendezvousConnectionOutcomeSource.Caller,
+                RendezvousConnectionFailureCategory.Lifecycle,
+                RendezvousConnectionPhase.Complete,
+                TimeSpan.Zero),
+            RendezvousConnectionState.TimedOut => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.DirectConnectTimedOut,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection,
+                TimeSpan.Zero),
+            RendezvousConnectionState.Rejected => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.HostRejected,
+                RendezvousConnectionOutcomeSource.RemoteHost,
+                RendezvousConnectionFailureCategory.Authorization,
+                RendezvousConnectionPhase.Authorization,
+                TimeSpan.Zero),
+            RendezvousConnectionState.ManagerStopped => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.ManagerStopped,
+                RendezvousConnectionOutcomeSource.Lifecycle,
+                RendezvousConnectionFailureCategory.Lifecycle,
+                RendezvousConnectionPhase.Complete,
+                TimeSpan.Zero),
+            RendezvousConnectionState.Disposed => RendezvousConnectionOutcome.Create(
+                ConnectionOutcomeKind.Disposed,
+                RendezvousConnectionOutcomeSource.Lifecycle,
+                RendezvousConnectionFailureCategory.Lifecycle,
+                RendezvousConnectionPhase.Complete,
+                TimeSpan.Zero),
+            RendezvousConnectionState.Connected => throw new ArgumentNullException(
+                nameof(peer),
+                "A connected completion requires a peer."),
+            _ => throw new ArgumentOutOfRangeException(
+                nameof(state),
+                state,
+                "A completion event requires a terminal connection state."),
+        };
+
+    internal static void Validate(
+        RendezvousConnectionState state,
+        RendezvousConnectionOutcome outcome)
+    {
+        if (outcome is null)
+        {
+            throw new ArgumentNullException(nameof(outcome));
+        }
+        if ((state == RendezvousConnectionState.Connected) != outcome.IsSuccess)
+        {
+            throw new ArgumentException(
+                "The connection state and typed outcome contradict each other.",
+                nameof(outcome));
+        }
+    }
 }
 
 public sealed class RendezvousCoordinatorOptions
@@ -29,8 +116,11 @@ public sealed class RendezvousCoordinatorOptions
     public int MaximumAttemptChecksPerPoll { get; set; } = 128;
     public TimeSpan InitialPunchRetryDelay { get; set; } = TimeSpan.FromMilliseconds(200);
     public TimeSpan MaximumPunchRetryDelay { get; set; } = TimeSpan.FromSeconds(2);
+    public TimeSpan PunchTimeout { get; set; } = TimeSpan.FromSeconds(10);
+    public TimeSpan DirectConnectTimeout { get; set; } = TimeSpan.FromSeconds(5);
     public TimeSpan ConnectionTicketLifetime { get; set; } = TimeSpan.FromSeconds(20);
     public double JitterRatio { get; set; } = 0.2;
+    public NetworkEndpoint? DedicatedFallbackOverride { get; set; }
 
     internal RendezvousCoordinatorOptions CopyAndValidate()
     {
@@ -39,9 +129,15 @@ public sealed class RendezvousCoordinatorOptions
             || InitialPunchRetryDelay < TimeSpan.FromMilliseconds(10)
             || MaximumPunchRetryDelay < InitialPunchRetryDelay
             || MaximumPunchRetryDelay > TimeSpan.FromSeconds(10)
+            || PunchTimeout <= TimeSpan.Zero
+            || PunchTimeout > TimeSpan.FromSeconds(30)
+            || DirectConnectTimeout <= TimeSpan.Zero
+            || DirectConnectTimeout > TimeSpan.FromSeconds(30)
             || ConnectionTicketLifetime <= TimeSpan.Zero
             || ConnectionTicketLifetime > TimeSpan.FromSeconds(20)
-            || JitterRatio is < 0 or > 1)
+            || JitterRatio is < 0 or > 1
+            || DedicatedFallbackOverride is not null
+                && !ContractValidation.IsNetworkEndpointValid(DedicatedFallbackOverride))
         {
             throw new ArgumentOutOfRangeException(nameof(RendezvousCoordinatorOptions));
         }
@@ -52,8 +148,11 @@ public sealed class RendezvousCoordinatorOptions
             MaximumAttemptChecksPerPoll = MaximumAttemptChecksPerPoll,
             InitialPunchRetryDelay = InitialPunchRetryDelay,
             MaximumPunchRetryDelay = MaximumPunchRetryDelay,
+            PunchTimeout = PunchTimeout,
+            DirectConnectTimeout = DirectConnectTimeout,
             ConnectionTicketLifetime = ConnectionTicketLifetime,
             JitterRatio = JitterRatio,
+            DedicatedFallbackOverride = RendezvousEndpoint.Copy(DedicatedFallbackOverride),
         };
     }
 }
@@ -61,11 +160,16 @@ public sealed class RendezvousCoordinatorOptions
 internal interface IRendezvousCoordinatorClock
 {
     DateTimeOffset UtcNow { get; }
+    TimeSpan Elapsed { get; }
 }
 
 internal sealed class SystemRendezvousCoordinatorClock : IRendezvousCoordinatorClock
 {
+    private readonly long _origin = Stopwatch.GetTimestamp();
+
     public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
+    public TimeSpan Elapsed => TimeSpan.FromSeconds(
+        (Stopwatch.GetTimestamp() - _origin) / (double)Stopwatch.Frequency);
 }
 
 internal static class RendezvousManagerGuard
@@ -95,11 +199,11 @@ internal sealed class RendezvousPunchRetrySchedule(
     IRendezvousCoordinatorClock clock)
 {
     public int RequestsSent { get; private set; }
-    public DateTimeOffset NextRequestAt { get; private set; } = DateTimeOffset.MinValue;
+    public TimeSpan NextRequestAt { get; private set; } = TimeSpan.Zero;
 
     public bool IsExhausted => RequestsSent >= options.MaximumPunchRequests;
 
-    public bool IsDue(DateTimeOffset now) => now >= NextRequestAt;
+    public bool IsDue(TimeSpan elapsed) => elapsed >= NextRequestAt;
 
     public void RecordRequest()
     {
@@ -119,6 +223,6 @@ internal sealed class RendezvousPunchRetrySchedule(
                 options.MaximumPunchRetryDelay.TotalMilliseconds);
         }
 
-        NextRequestAt = clock.UtcNow + TimeSpan.FromMilliseconds(milliseconds);
+        NextRequestAt = clock.Elapsed + TimeSpan.FromMilliseconds(milliseconds);
     }
 }

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousHostCoordinator.cs

@@ -1,4 +1,5 @@
 using System.Net;
+using System.Net.Sockets;
 using FinalFactory.Rendezvous.Contracts;
 using LiteNetLib;
 
@@ -11,14 +12,37 @@ public enum RendezvousHostState
     Disposed = 3,
 }
 
-public sealed class RendezvousHostAttemptCompletedEventArgs(
-    JoinAttemptId attemptId,
-    RendezvousConnectionState state,
-    NetPeer? peer = null) : EventArgs
+public sealed class RendezvousHostAttemptCompletedEventArgs : EventArgs
 {
-    public JoinAttemptId AttemptId { get; } = attemptId;
-    public RendezvousConnectionState State { get; } = state;
-    public NetPeer? Peer { get; } = peer;
+    [Obsolete("Completion events now expose a typed Outcome. Construct these arguments only for legacy test doubles.")]
+    public RendezvousHostAttemptCompletedEventArgs(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        NetPeer? peer)
+        : this(attemptId, state, RendezvousCompletionInvariant.FromLegacy(state, peer))
+    {
+    }
+
+    internal RendezvousHostAttemptCompletedEventArgs(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        RendezvousConnectionOutcome outcome)
+    {
+        if (attemptId.Value == Guid.Empty)
+        {
+            throw new ArgumentException("The completed attempt ID is invalid.", nameof(attemptId));
+        }
+
+        RendezvousCompletionInvariant.Validate(state, outcome);
+        AttemptId = attemptId;
+        State = state;
+        Outcome = outcome;
+    }
+
+    public JoinAttemptId AttemptId { get; }
+    public RendezvousConnectionState State { get; }
+    public RendezvousConnectionOutcome Outcome { get; }
+    public NetPeer? Peer => Outcome.Peer;
 }
 
 public sealed class RendezvousHostCoordinator : IDisposable
@@ -37,6 +61,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
     private readonly Dictionary<JoinAttemptId, DeferredConnectionRequest> _deferredRequests = [];
     private readonly Dictionary<JoinAttemptId, DateTimeOffset> _terminalAttempts = [];
     private readonly Queue<JoinAttemptId> _attemptSchedule = [];
+    private readonly SortedDictionary<long, Queue<HostAttemptDeadline>> _deadlines = [];
     private readonly List<JoinAttemptId> _cleanupScratch = [];
     private HostJoinAttempt[]? _latestSnapshot;
     private DateTimeOffset _nextPresenceAt = DateTimeOffset.MinValue;
@@ -90,6 +115,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
         _networkEvents.RendezvousConnectionRequest += OnConnectionRequest;
         _networkEvents.RendezvousPeerConnected += OnPeerConnected;
         _networkEvents.RendezvousPeerDisconnected += OnPeerDisconnected;
+        _networkEvents.RendezvousNetworkError += OnNetworkError;
         _punchEvents.NatIntroductionSuccess += OnNatIntroductionSuccess;
     }
 
@@ -161,7 +187,10 @@ public sealed class RendezvousHostCoordinator : IDisposable
             ApplySnapshots();
             if (!_manager.IsRunning)
             {
-                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                Stop(
+                    RendezvousHostState.ManagerStopped,
+                    RendezvousConnectionState.ManagerStopped,
+                    ConnectionOutcomeKind.ManagerStopped);
                 return;
             }
 
@@ -174,13 +203,23 @@ public sealed class RendezvousHostCoordinator : IDisposable
             }
 
             DateTimeOffset now = _clock.UtcNow;
+            TimeSpan elapsed = _clock.Elapsed;
             if (!_manager.IsRunning)
             {
-                Stop(RendezvousHostState.ManagerStopped, RendezvousConnectionState.ManagerStopped);
+                Stop(
+                    RendezvousHostState.ManagerStopped,
+                    RendezvousConnectionState.ManagerStopped,
+                    ConnectionOutcomeKind.ManagerStopped);
                 return;
             }
 
             RefreshPresence(now);
+            ProcessDueDeadlines(elapsed);
+            if (State != RendezvousHostState.Active)
+            {
+                return;
+            }
+
             int checks = Math.Min(
                 _attemptSchedule.Count,
                 _options.MaximumAttemptChecksPerPoll);
@@ -192,18 +231,22 @@ public sealed class RendezvousHostCoordinator : IDisposable
                     continue;
                 }
 
-                if (now >= attempt.Invitation.ExpiresAt)
+                if (attempt.State != RendezvousConnectionState.Punching)
                 {
-                    CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
                     continue;
                 }
 
-                if (attempt.State == RendezvousConnectionState.Punching
-                    && attempt.Retry.IsDue(now))
+                if (attempt.Retry.IsDue(elapsed))
                 {
                     if (attempt.Retry.IsExhausted)
                     {
-                        CompleteAttempt(attemptId, RendezvousConnectionState.TimedOut);
+                        CompleteAttempt(
+                            attemptId,
+                            RendezvousConnectionState.TimedOut,
+                            ConnectionOutcomeKind.PunchTimedOut,
+                            RendezvousConnectionOutcomeSource.LocalTraversal,
+                            RendezvousConnectionFailureCategory.NatTraversal,
+                            RendezvousConnectionPhase.NatTraversal);
                         continue;
                     }
 
@@ -251,9 +294,13 @@ public sealed class RendezvousHostCoordinator : IDisposable
             return;
         }
 
-        Stop(RendezvousHostState.Disposed, RendezvousConnectionState.Disposed);
+        Stop(
+            RendezvousHostState.Disposed,
+            RendezvousConnectionState.Disposed,
+            ConnectionOutcomeKind.Disposed);
         Interlocked.Exchange(ref _latestSnapshot, null);
         _attemptSchedule.Clear();
+        _deadlines.Clear();
         _terminalAttempts.Clear();
         _cleanupScratch.Clear();
         _tickets.Dispose();
@@ -272,6 +319,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
         }
 
         DateTimeOffset now = _clock.UtcNow;
+        TimeSpan elapsed = _clock.Elapsed;
         foreach (HostJoinAttempt invitation in latest)
         {
             if (invitation.AttemptId.Value == Guid.Empty
@@ -289,7 +337,11 @@ public sealed class RendezvousHostCoordinator : IDisposable
                 {
                     CompleteAttempt(
                         invitation.AttemptId,
-                        RendezvousConnectionState.Cancelled);
+                        RendezvousConnectionState.Cancelled,
+                        ConnectionOutcomeKind.Cancelled,
+                        RendezvousConnectionOutcomeSource.RendezvousService,
+                        RendezvousConnectionFailureCategory.Lifecycle,
+                        RendezvousConnectionPhase.Authorization);
                 }
 
                 _terminalAttempts[invitation.AttemptId] = invitation.ExpiresAt;
@@ -303,11 +355,23 @@ public sealed class RendezvousHostCoordinator : IDisposable
                 continue;
             }
 
+            TimeSpan attemptDeadline = elapsed + (invitation.ExpiresAt - now);
+            TimeSpan punchDeadline = Min(
+                attemptDeadline,
+                elapsed + _options.PunchTimeout);
             _attempts.Add(
                 invitation.AttemptId,
                 new PendingHostAttempt(
                     CopyAttempt(invitation),
-                    new RendezvousPunchRetrySchedule(_options, _clock)));
+                    new RendezvousPunchRetrySchedule(_options, _clock),
+                    elapsed,
+                    attemptDeadline,
+                    punchDeadline));
+            EnqueueDeadline(
+                new HostAttemptDeadline(
+                    invitation.AttemptId,
+                    RendezvousConnectionState.Punching,
+                    punchDeadline));
             _attemptSchedule.Enqueue(invitation.AttemptId);
         }
     }
@@ -354,6 +418,13 @@ public sealed class RendezvousHostCoordinator : IDisposable
         }
 
         attempt.State = RendezvousConnectionState.Connecting;
+        attempt.DirectDeadline = Min(
+            attempt.AttemptDeadline,
+            _clock.Elapsed + _options.DirectConnectTimeout);
+        EnqueueDeadline(new HostAttemptDeadline(
+            introduction.AttemptId,
+            RendezvousConnectionState.Connecting,
+            attempt.DirectDeadline.Value));
         if (_deferredRequests.Remove(
                 introduction.AttemptId,
                 out DeferredConnectionRequest? deferred))
@@ -410,7 +481,14 @@ public sealed class RendezvousHostCoordinator : IDisposable
     {
         if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
         {
-            CompleteAttempt(attemptId, RendezvousConnectionState.Connected, peer);
+            CompleteAttempt(
+                attemptId,
+                RendezvousConnectionState.Connected,
+                ConnectionOutcomeKind.Connected,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.None,
+                RendezvousConnectionPhase.Complete,
+                peer);
         }
     }
 
@@ -419,32 +497,113 @@ public sealed class RendezvousHostCoordinator : IDisposable
         _ = disconnectInfo;
         if (_acceptedPeers.TryGetValue(peer, out JoinAttemptId attemptId))
         {
-            CompleteAttempt(attemptId, RendezvousConnectionState.Rejected);
+            ConnectionOutcomeKind kind = disconnectInfo.Reason == DisconnectReason.Timeout
+                ? ConnectionOutcomeKind.DirectConnectTimedOut
+                : ConnectionOutcomeKind.TransportError;
+            CompleteAttempt(
+                attemptId,
+                kind == ConnectionOutcomeKind.DirectConnectTimedOut
+                    ? RendezvousConnectionState.TimedOut
+                    : RendezvousConnectionState.Rejected,
+                kind,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.DirectConnection,
+                RendezvousConnectionPhase.DirectConnection);
+        }
+    }
+
+    private void OnNetworkError(IPEndPoint endpoint, SocketError socketError)
+    {
+        _ = socketError;
+        if (!endpoint.Equals(_mediator))
+        {
+            return;
+        }
+
+        foreach (JoinAttemptId attemptId in _attempts
+                     .Where(static item => item.Value.State == RendezvousConnectionState.Punching)
+                     .Select(static item => item.Key)
+                     .ToArray())
+        {
+            CompleteAttempt(
+                attemptId,
+                RendezvousConnectionState.Rejected,
+                ConnectionOutcomeKind.MediatorUnavailable,
+                RendezvousConnectionOutcomeSource.LocalTraversal,
+                RendezvousConnectionFailureCategory.Mediation,
+                RendezvousConnectionPhase.Mediation);
         }
     }
 
     private void CompleteAttempt(
         JoinAttemptId attemptId,
         RendezvousConnectionState state,
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
         NetPeer? peer = null)
     {
+        if (TryCompleteAttempt(
+                attemptId,
+                state,
+                kind,
+                source,
+                category,
+                phase,
+                peer,
+                out RendezvousHostAttemptCompletedEventArgs? completion))
+        {
+            AttemptCompleted?.Invoke(this, completion!);
+        }
+    }
+
+    private bool TryCompleteAttempt(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState state,
+        ConnectionOutcomeKind kind,
+        RendezvousConnectionOutcomeSource source,
+        RendezvousConnectionFailureCategory category,
+        RendezvousConnectionPhase phase,
+        NetPeer? peer,
+        out RendezvousHostAttemptCompletedEventArgs? completion)
+    {
+        completion = null;
         if (!_attempts.Remove(attemptId, out PendingHostAttempt? attempt))
         {
-            return;
+            return false;
         }
 
         if (attempt.AcceptedPeer is not null)
         {
             _acceptedPeers.Remove(attempt.AcceptedPeer);
+            if (kind != ConnectionOutcomeKind.Connected)
+            {
+                attempt.AcceptedPeer.Disconnect();
+            }
         }
 
-        _deferredRequests.Remove(attemptId);
+        if (_deferredRequests.Remove(attemptId, out DeferredConnectionRequest? deferred))
+        {
+            deferred.Request.RejectForce([]);
+        }
         _tickets.Revoke(attemptId);
         _terminalAttempts[attemptId] = attempt.Invitation.ExpiresAt;
-        AttemptCompleted?.Invoke(this, new(attemptId, state, peer));
+        RendezvousConnectionOutcome outcome = RendezvousConnectionOutcome.Create(
+            kind,
+            source,
+            category,
+            phase,
+            _clock.Elapsed - attempt.StartedAt,
+            peer: peer);
+        completion = new(attemptId, state, outcome);
+        return true;
     }
 
-    private void Stop(RendezvousHostState hostState, RendezvousConnectionState attemptState)
+    private void Stop(
+        RendezvousHostState hostState,
+        RendezvousConnectionState attemptState,
+        ConnectionOutcomeKind outcomeKind)
     {
         if (State != RendezvousHostState.Active)
         {
@@ -452,12 +611,32 @@ public sealed class RendezvousHostCoordinator : IDisposable
         }
 
         State = hostState;
+        List<RendezvousHostAttemptCompletedEventArgs> completions = [];
         foreach (JoinAttemptId attemptId in _attempts.Keys.ToArray())
         {
-            CompleteAttempt(attemptId, attemptState);
+            RendezvousConnectionPhase phase = _attempts[attemptId].State
+                == RendezvousConnectionState.Connecting
+                    ? RendezvousConnectionPhase.DirectConnection
+                    : RendezvousConnectionPhase.NatTraversal;
+            if (TryCompleteAttempt(
+                    attemptId,
+                    attemptState,
+                    outcomeKind,
+                    RendezvousConnectionOutcomeSource.Lifecycle,
+                    RendezvousConnectionFailureCategory.Lifecycle,
+                    phase,
+                    null,
+                    out RendezvousHostAttemptCompletedEventArgs? completion))
+            {
+                completions.Add(completion!);
+            }
         }
 
         ReleaseSubscriptions();
+        foreach (RendezvousHostAttemptCompletedEventArgs completion in completions)
+        {
+            AttemptCompleted?.Invoke(this, completion);
+        }
     }
 
     private void ReleaseSubscriptions()
@@ -470,6 +649,7 @@ public sealed class RendezvousHostCoordinator : IDisposable
         _networkEvents.RendezvousConnectionRequest -= OnConnectionRequest;
         _networkEvents.RendezvousPeerConnected -= OnPeerConnected;
         _networkEvents.RendezvousPeerDisconnected -= OnPeerDisconnected;
+        _networkEvents.RendezvousNetworkError -= OnNetworkError;
         _punchEvents.NatIntroductionSuccess -= OnNatIntroductionSuccess;
         _subscriptionsReleased = true;
     }
@@ -496,9 +676,78 @@ public sealed class RendezvousHostCoordinator : IDisposable
         ExpiresAt = attempt.ExpiresAt,
     };
 
+    private static TimeSpan Min(TimeSpan left, TimeSpan right) =>
+        left <= right ? left : right;
+
     private static DateTimeOffset Min(DateTimeOffset left, DateTimeOffset right) =>
         left <= right ? left : right;
 
+    private void EnqueueDeadline(HostAttemptDeadline deadline)
+    {
+        if (!_deadlines.TryGetValue(deadline.Deadline.Ticks, out Queue<HostAttemptDeadline>? bucket))
+        {
+            bucket = new Queue<HostAttemptDeadline>();
+            _deadlines.Add(deadline.Deadline.Ticks, bucket);
+        }
+
+        bucket.Enqueue(deadline);
+    }
+
+    private void ProcessDueDeadlines(TimeSpan elapsed)
+    {
+        while (_deadlines.Count > 0)
+        {
+            KeyValuePair<long, Queue<HostAttemptDeadline>> first = _deadlines.First();
+            if (first.Key > elapsed.Ticks)
+            {
+                return;
+            }
+
+            HostAttemptDeadline deadline = first.Value.Dequeue();
+            if (first.Value.Count == 0)
+            {
+                _deadlines.Remove(first.Key);
+            }
+
+            if (!_attempts.TryGetValue(deadline.AttemptId, out PendingHostAttempt? attempt)
+                || attempt.State != deadline.ExpectedState
+                || (deadline.ExpectedState == RendezvousConnectionState.Punching
+                    ? attempt.PunchDeadline
+                    : attempt.DirectDeadline) != deadline.Deadline)
+            {
+                continue;
+            }
+
+            bool expired = elapsed >= attempt.AttemptDeadline;
+            CompleteAttempt(
+                deadline.AttemptId,
+                RendezvousConnectionState.TimedOut,
+                expired
+                    ? ConnectionOutcomeKind.AttemptExpired
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? ConnectionOutcomeKind.PunchTimedOut
+                        : ConnectionOutcomeKind.DirectConnectTimedOut,
+                expired
+                    ? RendezvousConnectionOutcomeSource.RendezvousService
+                    : RendezvousConnectionOutcomeSource.LocalTraversal,
+                expired
+                    ? RendezvousConnectionFailureCategory.Authorization
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? RendezvousConnectionFailureCategory.NatTraversal
+                        : RendezvousConnectionFailureCategory.DirectConnection,
+                expired
+                    ? RendezvousConnectionPhase.Authorization
+                    : deadline.ExpectedState == RendezvousConnectionState.Punching
+                        ? RendezvousConnectionPhase.NatTraversal
+                        : RendezvousConnectionPhase.DirectConnection);
+
+            if (State != RendezvousHostState.Active)
+            {
+                return;
+            }
+        }
+    }
+
     private void AcceptAuthorizedRequest(
         JoinAttemptId attemptId,
         PendingHostAttempt attempt,
@@ -529,14 +778,31 @@ public sealed class RendezvousHostCoordinator : IDisposable
 
     private sealed class PendingHostAttempt(
         HostJoinAttempt invitation,
-        RendezvousPunchRetrySchedule retry)
+        RendezvousPunchRetrySchedule retry,
+        TimeSpan startedAt,
+        TimeSpan attemptDeadline,
+        TimeSpan punchDeadline)
     {
         internal HostJoinAttempt Invitation { get; } = invitation;
         internal RendezvousPunchRetrySchedule Retry { get; } = retry;
+        internal TimeSpan StartedAt { get; } = startedAt;
+        internal TimeSpan AttemptDeadline { get; } = attemptDeadline;
+        internal TimeSpan PunchDeadline { get; } = punchDeadline;
+        internal TimeSpan? DirectDeadline { get; set; }
         internal RendezvousConnectionState State { get; set; } = RendezvousConnectionState.Punching;
         internal NetPeer? AcceptedPeer { get; set; }
     }
 
+    private sealed class HostAttemptDeadline(
+        JoinAttemptId attemptId,
+        RendezvousConnectionState expectedState,
+        TimeSpan deadline)
+    {
+        internal JoinAttemptId AttemptId { get; } = attemptId;
+        internal RendezvousConnectionState ExpectedState { get; } = expectedState;
+        internal TimeSpan Deadline { get; } = deadline;
+    }
+
     private sealed class DeferredConnectionRequest(
         ConnectionRequest request,
         string connectionTicket)

src/FinalFactory.Rendezvous.Client/Traversal/RendezvousNetListener.cs

@@ -29,6 +29,7 @@ public sealed class RendezvousNetListener : INetEventListener
     internal event Action<NetPeer>? RendezvousPeerConnected;
     internal event Action<NetPeer, DisconnectInfo>? RendezvousPeerDisconnected;
     internal event Action<ConnectionRequest>? RendezvousConnectionRequest;
+    internal event Action<IPEndPoint, SocketError>? RendezvousNetworkError;
 
     internal void ValidateManager(NetManager manager)
     {
@@ -51,8 +52,11 @@ public sealed class RendezvousNetListener : INetEventListener
         ((INetEventListener)GameplayEvents).OnPeerDisconnected(peer, disconnectInfo);
     }
 
-    public void OnNetworkError(IPEndPoint endPoint, SocketError socketError) =>
+    public void OnNetworkError(IPEndPoint endPoint, SocketError socketError)
+    {
+        RendezvousNetworkError?.Invoke(endPoint, socketError);
         ((INetEventListener)GameplayEvents).OnNetworkError(endPoint, socketError);
+    }
 
     public void OnNetworkReceive(
         NetPeer peer,