Availability Strategy: Fixes HedgeContext diagnostics to only appear when hedging occurs (#5665)

## Summary

Fixes misleading Hedge Context diagnostics in
CrossRegionHedgingAvailabilityStrategy. Previously, HedgeContext was
**always** populated when a request went through the hedging strategy
code path — even when no cross-region hedging actually occurred (primary
request completed before the threshold). This caused customer confusion
because:

1. A single-element HedgeContext (e.g., `["East US 2"]`) was
indistinguishable from "no hedging" without counting elements
2. When PPAF (Per-Partition Automatic Failover) transparently redirected
a request at the transport layer, HedgeContext showed the hedging
strategy's intended target — not the actual servicing region — creating
a mismatch with ContactedReplicas

## Root Cause

In
`CrossRegionHedgingAvailabilityStrategy.ExecuteAvailabilityStrategyAsync`,
the for-loop exit path unconditionally set `HedgeContext =
hedgeRegions.Take(requestNumber + 1)` (line 226-228). When
`requestNumber=0` (primary request completed before the threshold timer
fired), this yielded a single-element list — making it look like hedging
occurred when it didn't.

## Fix

Added `if (requestNumber > 0)` guard around the `HedgeContext` and
`Response Region` writes in the for-loop exit path. `Hedge Config` is
always written (pre-computed string, zero overhead).

**New semantics:**
- `HedgeContext` **present** = cross-region hedging was triggered
(threshold timer fired, additional requests dispatched to other regions)
- `HedgeContext` **absent** = no hedging occurred (primary request
completed before threshold)
- `Hedge Config` always present when hedging strategy code path is used

**Impact:** One `if` statement added. Zero new fields, zero new
allocations, zero additional diagnostics overhead.

## Customer Scenario (Investigation)

An internal customer reported two cases where hedging diagnostics were
confusing:

**Case 1 — Latency < threshold:** Request completed in ~38ms (threshold:
1000ms). Customer expected `HedgeContext` to be empty since no hedging
occurred. Actual: `HedgeContext: ["Central US"]` (single region =
primary completed first, no hedging).

**Case 2 — PPAF redirect:** Request was sent to East US 2 but PPAF
detected quorum loss and redirected to Central US at the transport layer
(not via hedging). Customer expected `HedgeContext: ["East US 2",
"Central US"]`. Actual: `HedgeContext: ["East US 2"]` because the
hedging strategy didn't know about the PPAF redirect.

Both cases showed **expected SDK behavior** but the diagnostics were
misleading. This fix addresses Case 1 by making `HedgeContext` absent
when no hedging occurs. Case 2 is inherent to the layered architecture
(PPAF operates below hedging) and would require a separate cross-layer
change if needed.

## Changes

| File | Change |
|------|--------|
| `CrossRegionHedgingAvailabilityStrategy.cs` | Added `if (requestNumber
> 0)` guard around `HedgeContext`/`ResponseRegion` writes |
| `AvailabilityStrategyUnitTests.cs` | Added 2 new tests:
`PrimaryCompletesBeforeThreshold_HedgeContextContainsSingleRegion`
(asserts `HedgeContext` absent) and
`HedgeTriggered_HedgeContextContainsMultipleRegions` (asserts
`HedgeContext` present with 2+ regions) |
| `RegionFailoverTests.cs` | Updated PPAF test assertion —
`HedgeContext` is now correctly absent when PPAF handles failover
internally (no cross-region hedging) |

## Testing

- **13/13** `AvailabilityStrategyUnitTests` pass
- **5/5** `RegionFailoverTests` pass (mock-based PPAF scenarios)
- **2/2** `CosmosItemIntegrationTests.ReadItemAsync_WithPPAFEnabled...`
pass (live multi-region account)
- **All** `CosmosAvailabilityStrategyTests` unaffected (they inject
faults that exceed threshold → hedging always triggers → `requestNumber
> 0`)

## Before/After Diagnostics

### Scenario 1: Primary request completes before threshold (no hedging)

**Before:**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 37.95,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False",
    "Hedge Context": ["Central US"],
    "Response Region": "Central US"
  }
}
```

**After:**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 37.95,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False"
  }
}
```

> `Hedge Context` and `Response Region` are absent — clearly indicating
no hedging occurred. `Hedge Config` remains so the configuration is
always visible.

### Scenario 2: Hedging triggered (primary slow, hedge responds first)

**Before (unchanged):**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 1693.89,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False",
    "Hedge Context": ["West US 2", "East US", "Central US"],
    "Response Region": "East US"
  }
}
```

**After (same — no change when hedging occurs):**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 1693.89,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False",
    "Hedge Context": ["West US 2", "East US", "Central US"],
    "Response Region": "East US"
  }
}
```

> When hedging is triggered, diagnostics are identical to before. `Hedge
Context` lists all regions that had requests dispatched, `Response
Region` shows which region's response was used.

### Scenario 3: PPAF redirects internally (no cross-region hedging)

**Before:**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 317.51,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False",
    "Hedge Context": ["East US 2"],
    "Response Region": "East US 2"
  },
  "children": [{ "...ContactedReplicas showing Central US replicas..." }]
}
```

**After:**
```json
{
  "name": "ReadItemAsync",
  "duration in milliseconds": 317.51,
  "data": {
    "Hedge Config": "t:1000ms, s:500ms, w:False"
  },
  "children": [{ "...ContactedReplicas showing Central US replicas..." }]
}
```

> The misleading `Hedge Context: ["East US 2"]` and `Response Region:
East US 2` are no longer present. The PPAF redirect is still visible in
the `ContactedReplicas` and `StoreResponseStatistics` within the
diagnostics children — which is the correct layer for this information.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Kiran Kumar Kolli <kirankk@microsoft.com>

Author: 3 people

Microsoft.Azure.Cosmos/src/Routing/AvailabilityStrategy/CrossRegionHedgingAvailabilityStrategy.cs

@@ -222,14 +222,19 @@ internal override async Task<ResponseMessage> ExecuteAvailabilityStrategyAsync(
                                     ((CosmosTraceDiagnostics)hedgeResponse.ResponseMessage.Diagnostics).Value.AddOrUpdateDatum(
                                         HedgeConfig,
                                         this.HedgeConfigText);
-                                    //Take is not inclusive, so we need to add 1 to the request number which starts at 0
-                                    ((CosmosTraceDiagnostics)hedgeResponse.ResponseMessage.Diagnostics).Value.AddOrUpdateDatum(
-                                        HedgeContext,
-                                        hedgeRegions.Take(requestNumber + 1));
-                                    // Note that the target region can be seperate than the actual region that serviced the request depending on the scenario
-                                    ((CosmosTraceDiagnostics)hedgeResponse.ResponseMessage.Diagnostics).Value.AddOrUpdateDatum(
-                                        ResponseRegion,
-                                        hedgeResponse.TargetRegionName);
+
+                                    if (requestNumber > 0)
+                                    {
+                                        //Take is not inclusive, so we need to add 1 to the request number which starts at 0
+                                        ((CosmosTraceDiagnostics)hedgeResponse.ResponseMessage.Diagnostics).Value.AddOrUpdateDatum(
+                                            HedgeContext,
+                                            hedgeRegions.Take(requestNumber + 1));
+                                        // Note that the target region can be seperate than the actual region that serviced the request depending on the scenario
+                                        ((CosmosTraceDiagnostics)hedgeResponse.ResponseMessage.Diagnostics).Value.AddOrUpdateDatum(
+                                            ResponseRegion,
+                                            hedgeResponse.TargetRegionName);
+                                    }
+
                                     return hedgeResponse.ResponseMessage;
                                 }
                             }

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTests/CosmosItemIntegrationTests.cs

@@ -1713,10 +1713,10 @@ public async Task ReadItemAsync_WithPPAFDynamicOverride_ShouldEnableOrDisablePPA
 
                 traceDiagnostic.Value.Data.TryGetValue("Hedge Context", out object hedgeContext);
 
-                Assert.IsNotNull(hedgeContext);
-                List<string> hedgedRegions = ((IEnumerable<string>)hedgeContext).ToList();
-
-                Assert.IsTrue(hedgedRegions.Count >= 1, "Since the first region is not available, the request should atleast hedge to the next region.");
+                // When PPAF is enabled, the primary request handles failover internally
+                // (retrying to another region at the transport layer). No cross-region
+                // hedging occurs, so HedgeContext should be absent.
+                Assert.IsNull(hedgeContext);
                 Assert.IsTrue(cosmosClient.DocumentClient.PartitionKeyRangeLocation.IsPartitionLevelAutomaticFailoverEnabled());
 
                 // Disable PPAF At the Gateway Layer.

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/AvailabilityStrategyUnitTests.cs

@@ -4,11 +4,14 @@
     using System.Collections.Generic;
     using System.Collections.ObjectModel;
     using System.IO;
+    using System.Linq;
     using System.Net;
     using System.Net.Http;
     using System.Threading;
     using System.Threading.Tasks;
     using Microsoft.Azure.Cosmos;
+    using Microsoft.Azure.Cosmos.Diagnostics;
+    using Microsoft.Azure.Cosmos.Tracing;
     using Microsoft.Azure.Documents;
     using Microsoft.VisualStudio.TestTools.UnitTesting;
 
@@ -632,6 +635,139 @@ public async Task FaultedHedgeTask_DoesNotAbortWhenOtherRegionSucceeds()
             Assert.IsTrue(senderCallCount >= 2, "Expected a second hedge request to complete successfully.");
         }
 
-       
+        /// <summary>
+        /// Verifies that when a request completes before the hedge threshold, HedgeContext
+        /// contains exactly 1 region (the primary). This confirms no hedging occurred even 
+        /// though HedgeContext is non-empty. A single-element HedgeContext is the expected
+        /// indicator that the primary request completed without triggering any hedge.
+        /// </summary>
+        [TestMethod]
+        public async Task PrimaryCompletesBeforeThreshold_HedgeContextContainsSingleRegion()
+        {
+            // Arrange: high threshold ensures no hedging fires
+            CrossRegionHedgingAvailabilityStrategy availabilityStrategy = new CrossRegionHedgingAvailabilityStrategy(
+                threshold: TimeSpan.FromMilliseconds(5000),
+                thresholdStep: TimeSpan.FromMilliseconds(5000));
+
+            // Use a real trace so AddOrUpdateDatum actually persists data (NoOpTrace discards it)
+            using ITrace rootTrace = Trace.GetRootTrace("HedgeContextTest");
+            using RequestMessage request = new RequestMessage(
+                HttpMethod.Get,
+                "/dbs/testdb/colls/testcontainer/docs/testId",
+                rootTrace)
+            {
+                ResourceType = ResourceType.Document,
+                OperationType = OperationType.Read
+            };
+            using CosmosClient mockCosmosClient = CreateMockClientWithRegions(3);
+
+            int senderCallCount = 0;
+
+            Func<RequestMessage, CancellationToken, Task<ResponseMessage>> sender = (req, ct) =>
+            {
+                Interlocked.Increment(ref senderCallCount);
+                ResponseMessage response = new ResponseMessage(HttpStatusCode.OK)
+                {
+                    Trace = req.Trace
+                };
+                return Task.FromResult(response);
+            };
+
+            // Act
+            ResponseMessage response = await availabilityStrategy.ExecuteAvailabilityStrategyAsync(
+                sender, mockCosmosClient, request, CancellationToken.None);
+
+            // Assert
+            Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
+            Assert.AreEqual(1, senderCallCount,
+                "Only the primary request should be sent when it returns before the hedge timer fires.");
+
+            CosmosTraceDiagnostics traceDiagnostic = response.Diagnostics as CosmosTraceDiagnostics;
+            Assert.IsNotNull(traceDiagnostic);
+
+            if (traceDiagnostic.Value is Trace concreteTrace)
+            {
+                concreteTrace.SetWalkingStateRecursively();
+            }
+
+            Assert.IsFalse(traceDiagnostic.Value.Data.TryGetValue("Hedge Context", out _),
+                "HedgeContext should be absent when the primary request completes before the threshold (no hedging occurred).");
+
+            Assert.IsTrue(traceDiagnostic.Value.Data.TryGetValue("Hedge Config", out _),
+                "Hedge Config should always be present when the hedging strategy code path is used.");
+        }
+
+        /// <summary>
+        /// Verifies that when hedging IS triggered (primary is slow, hedge returns first),
+        /// HedgeContext contains 2 regions — confirming the semantics that HedgeContext count > 1 
+        /// means hedging occurred.
+        /// </summary>
+        [TestMethod]
+        public async Task HedgeTriggered_HedgeContextContainsMultipleRegions()
+        {
+            // Arrange: low threshold ensures hedging fires quickly
+            CrossRegionHedgingAvailabilityStrategy availabilityStrategy = new CrossRegionHedgingAvailabilityStrategy(
+                threshold: TimeSpan.FromMilliseconds(10),
+                thresholdStep: TimeSpan.FromMilliseconds(10));
+
+            // Use a real trace so AddOrUpdateDatum actually persists data
+            using ITrace rootTrace = Trace.GetRootTrace("HedgeContextTest");
+            using RequestMessage request = new RequestMessage(
+                HttpMethod.Get,
+                "/dbs/testdb/colls/testcontainer/docs/testId",
+                rootTrace)
+            {
+                ResourceType = ResourceType.Document,
+                OperationType = OperationType.Read
+            };
+            using CosmosClient mockCosmosClient = CreateMockClientWithRegions(3);
+
+            int senderCallCount = 0;
+
+            Func<RequestMessage, CancellationToken, Task<ResponseMessage>> sender = async (req, ct) =>
+            {
+                int callNumber = Interlocked.Increment(ref senderCallCount);
+
+                if (callNumber == 1)
+                {
+                    // Primary: slow enough to trigger hedging
+                    await Task.Delay(TimeSpan.FromSeconds(5), ct).ContinueWith(_ => { });
+                    return new ResponseMessage(HttpStatusCode.ServiceUnavailable);
+                }
+
+                // Hedge request: returns immediately with success, wired to request trace
+                return new ResponseMessage(HttpStatusCode.OK)
+                {
+                    Trace = req.Trace
+                };
+            };
+
+            // Act
+            ResponseMessage response = await availabilityStrategy.ExecuteAvailabilityStrategyAsync(
+                sender, mockCosmosClient, request, CancellationToken.None);
+
+            // Assert
+            Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
+            Assert.IsTrue(senderCallCount >= 2,
+                "At least 2 sender calls expected (primary + hedge).");
+
+            CosmosTraceDiagnostics traceDiagnostic = response.Diagnostics as CosmosTraceDiagnostics;
+            Assert.IsNotNull(traceDiagnostic);
+
+            if (traceDiagnostic.Value is Trace concreteTrace)
+            {
+                concreteTrace.SetWalkingStateRecursively();
+            }
+
+            Assert.IsTrue(traceDiagnostic.Value.Data.TryGetValue("Hedge Context", out object hedgeContext),
+                "HedgeContext should be present when hedging occurred.");
+
+            IEnumerable<string> hedgeRegions = (IEnumerable<string>)hedgeContext;
+            List<string> hedgeRegionsList = new List<string>(hedgeRegions);
+
+            Assert.IsTrue(hedgeRegionsList.Count >= 2,
+                $"HedgeContext should contain 2+ regions when hedging occurred, but got {hedgeRegionsList.Count}. " +
+                "Multiple regions in HedgeContext confirms hedging was triggered.");
+        }
     }
 }

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/PartitionKeyRangeFailoverTests/RegionFailoverTests.cs

@@ -355,11 +355,11 @@ public async Task ReadItemAsync_WithThinClientEnabledAndServiceUnavailableReceiv
 
                     if (enablePartitionLevelFailover)
                     {
-                        Assert.IsNotNull(hedgeContext);
-                        List<string> hedgedRegions = ((IEnumerable<string>)hedgeContext).ToList();
-
-                        Assert.IsTrue(hedgedRegions.Count >= 1, "Since the first region is not available, the request should atleast hedge to the next region.");
-                        Assert.IsTrue(hedgedRegions.Contains(Regions.EastUS));
+                        // When PPAF is enabled, the primary request handles failover internally
+                        // (retrying to another region). No cross-region hedging occurs, so
+                        // HedgeContext should be absent. The failover is visible in the
+                        // diagnostics children (multiple RouterHandler/TransportHandler nodes).
+                        Assert.IsNull(hedgeContext);
                     }
                     else
                     {