Checkpoint all current runtime, benchmark and website changes

Capture the complete current working-tree scope on main, including typed
runtime configuration, benchmark/vector contracts, telemetry and tests,
independent website development evidence, and documentation updates.

Verification checkpoint: the preceding full Release solution build failed
with 372 errors in the shared implementation. The SiteTests project build,
no-benchmark site smoke build, and syntax/governance checks passed in the
preceding verification. Aspire-owned suites and live Pages qualification
remain unverified; this checkpoint does not claim acceptance or readiness.

Author: KSemenenko

benchmarks/KeyLoad.ComparisonHost/Features/BenchmarkComparisons/Hosting/IsolatedHostTargetOwner.cs

@@ -9,8 +9,9 @@ namespace KeyLoad.ComparisonHost.Features.BenchmarkComparisons;
 /// <summary>Owns only one native target and tracks partial HTTP construction until ownership transfers.</summary>
 internal sealed class IsolatedHostTargetOwner(IOptions<NativeComparisonExecutionOptions> executionOptions) : IAsyncDisposable
 {
-    private readonly NativeComparisonExecutionOptions policy = executionOptions.Value.Validate();
-    internal IOptions<NativeComparisonExecutionOptions> ExecutionOptions => executionOptions;
+    private readonly IOptions<NativeComparisonExecutionOptions> execution = NativeComparisonExecutionOptions.Require(executionOptions);
+    private NativeComparisonExecutionOptions Policy => execution.Value;
+    internal IOptions<NativeComparisonExecutionOptions> ExecutionOptions => execution;
     private readonly List<HttpClient> unownedClients = [];
     private IComparisonTarget? target;
     private IVectorComparisonTarget? vectorTarget;
@@ -118,7 +119,7 @@ public async ValueTask DisposeAsync()
             if (ownedVectorTarget is not null)
             {
                 var cleanup = ownedVectorTarget.DisposeAsync().AsTask();
-                await cleanup.WaitAsync(policy.CleanupTimeout);
+                await cleanup.WaitAsync(Policy.CleanupTimeout);
             }
         }
         finally
@@ -136,7 +137,7 @@ private async Task DisposeTargetAsync(IComparisonTarget ownedTarget)
         var cleanup = ownedTarget.DisposeAsync().AsTask();
         try
         {
-            await cleanup.WaitAsync(policy.CleanupTimeout);
+            await cleanup.WaitAsync(Policy.CleanupTimeout);
         }
         catch (Exception)
         {

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Configuration/ComparisonWorkerSelectionOptions.cs

@@ -0,0 +1,72 @@
+namespace KeyLoad.Comparisons;
+
+/// <summary>Holds trusted isolated worker selectors and detects forbidden immutable-workload overrides.</summary>
+[ConfigurationOptions]
+public sealed class ComparisonWorkerSelectionOptions
+{
+    /// <summary>Names the workflow selector section.</summary>
+    public const string SectionName = "Benchmarks";
+
+    /// <summary>Gets or sets the canonical engine name.</summary>
+    public string? Target { get; set; }
+
+    /// <summary>Gets or sets the actual native member count.</summary>
+    public string? NodeCount { get; set; }
+
+    /// <summary>Gets or sets the exact workload scenario.</summary>
+    public string? Scenario { get; set; }
+
+    /// <summary>Gets or sets the authenticated profile identifier.</summary>
+    public string? EvidenceProfile { get; set; }
+
+    /// <summary>Gets or sets the optional immutable scale profile.</summary>
+    public string? ScaleProfile { get; set; }
+
+    /// <summary>Gets or sets the optional immutable vector profile.</summary>
+    public string? VectorProfile { get; set; }
+
+    /// <summary>Gets or sets the optional offered-rate cohort.</summary>
+    public string? OpenLoopRate { get; set; }
+
+    /// <summary>Gets or sets the optional AppHost mode.</summary>
+    public string? Profile { get; set; }
+
+    /// <summary>Gets or sets the document count override.</summary>
+    public string? Documents { get; set; }
+
+    /// <summary>Gets or sets the operation count override.</summary>
+    public string? Operations { get; set; }
+
+    /// <summary>Gets or sets the warmup override.</summary>
+    public string? Warmup { get; set; }
+
+    /// <summary>Gets or sets the repetition override.</summary>
+    public string? Repetitions { get; set; }
+
+    /// <summary>Gets or sets the concurrency override.</summary>
+    public string? Concurrency { get; set; }
+
+    /// <summary>Gets or sets the payload size override.</summary>
+    public string? PayloadBytes { get; set; }
+
+    /// <summary>Gets or sets the seed override.</summary>
+    public string? Seed { get; set; }
+
+    /// <summary>Gets or sets the vector dimension override.</summary>
+    public string? Dimensions { get; set; }
+
+    /// <summary>Gets or sets the neighbor count override.</summary>
+    public string? TopK { get; set; }
+
+    /// <summary>Gets or sets the operation timeout override.</summary>
+    public string? TimeoutSeconds { get; set; }
+
+    /// <summary>Gets or sets the graph vertex override.</summary>
+    public string? GraphVertices { get; set; }
+
+    /// <summary>Gets or sets the graph fan-out override.</summary>
+    public string? GraphFanOut { get; set; }
+
+    /// <summary>Gets or sets the graph depth override.</summary>
+    public string? GraphDepth { get; set; }
+}

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Configuration/NativeComparisonExecutionOptions.cs

@@ -34,6 +34,16 @@ public sealed class NativeComparisonExecutionOptions
     /// <summary>The interval between native index completion checks.</summary>
     public TimeSpan IndexPollInterval { get; set; }
 
+    /// <summary>Validates the injected wrapper before any native target is created.</summary>
+    /// <param name="options">The centrally bound options.</param>
+    /// <returns>The validated native options wrapper.</returns>
+    public static IOptions<NativeComparisonExecutionOptions> Require(IOptions<NativeComparisonExecutionOptions> options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Value.Validate();
+        return options;
+    }
+
     /// <summary>Rejects omitted or inconsistent operational configuration.</summary>
     /// <returns>This validated policy.</returns>
     public NativeComparisonExecutionOptions Validate()

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Contracts/ComparisonWorkerSelectionValues.cs

@@ -52,7 +52,7 @@ private static async Task<ReadOnlyMemory<byte>> ReadBodyAsync(HttpContent conten
                     throw new ComparisonFailureException(LimitFailure);
                 }
 
-                body.Write(buffer, EmptyResultCount, count);
+                await body.WriteAsync(buffer.AsMemory(EmptyResultCount, count), token).ConfigureAwait(false);
             }
 
             return body.GetBuffer().AsMemory(EmptyResultCount, checked((int)body.Length));

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Serialization/NativeComparisonResponse.cs

@@ -6,6 +6,9 @@ namespace KeyLoad.Comparisons;
 /// <summary>Serializes and strictly reconstitutes one of the exact closed scaled profile identities.</summary>
 public sealed class ScaledComparisonProfileJsonConverter : JsonConverter<ScaledComparisonProfile>
 {
+    private const int PropertyCount = 14;
+    private const string InvalidShape = "Scaled profile shape is invalid.";
+    private const string SettingsMismatch = "Scaled profile settings mismatch.";
     private const string ConcurrencyProperty = "concurrency";
     private const string DimensionsProperty = "dimensions";
     private const string DocumentsProperty = "documents";
@@ -25,10 +28,10 @@ public override ScaledComparisonProfile Read(ref Utf8JsonReader reader, Type typ
     {
         using var document = JsonDocument.ParseValue(ref reader);
         var root = document.RootElement;
-        if (root.ValueKind != JsonValueKind.Object || root.EnumerateObject().Count() != 14
+        if (root.ValueKind != JsonValueKind.Object || root.EnumerateObject().Count() != PropertyCount
             || !root.TryGetProperty(IdProperty, out var id) || id.ValueKind != JsonValueKind.String)
         {
-            throw new JsonException("Scaled profile shape is invalid.");
+            throw new JsonException(InvalidShape);
         }
         var profile = ScaledComparisonProfileParser.Parse(id.GetString()!);
         Validate(root, profile);
@@ -68,7 +71,7 @@ private static void Require(JsonElement root, string name, int expected)
         if (!root.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Number
             || !value.TryGetInt32(out var actual) || actual != expected)
         {
-            throw new JsonException("Scaled profile settings mismatch.");
+            throw new JsonException(SettingsMismatch);
         }
     }
 

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Serialization/ScaledComparisonProfileJsonConverter.cs

@@ -7,6 +7,7 @@ namespace KeyLoad.Comparisons.Targets;
 internal static class HelixDbIndexLifecycle
 {
     private const string ProviderNativeANNOpaqueTuning = "provider-native ANN; opaque tuning";
+    private const string CompletedOperation = "; completed operation=";
     private const string CompletedReceipt = "; completed receipt=";
     private const int SingleResultCardinality = 1;
     private const int EmptyResultCount = 0;
@@ -24,8 +25,8 @@ internal static async Task<string> ExecuteAsync(HttpClient http, JsonObject defi
         }
 
         var operation = receipt.GetProperty(HelixDbNativeTokens.TokenOperationId).GetString()!;
-        await WaitAsync(http, operation, policy, token).ConfigureAwait(false);
-        return receipt.GetRawText();
+        var completion = await WaitAsync(http, operation, policy, token).ConfigureAwait(false);
+        return receipt.GetRawText() + CompletedOperation + completion;
     }
 
     internal static async Task<VectorIndexReceipt> BuildAsync(HttpClient http, string label, int dimensions, NativeComparisonExecutionOptions policy, CancellationToken token)
@@ -45,17 +46,18 @@ internal static async Task<VectorIndexReceipt> BuildAsync(HttpClient http, strin
         return new(VectorIndexKind.NativeAnn, definition.ToJsonString() + CompletedReceipt + receipt, parameters, watch.Elapsed.TotalMilliseconds);
     }
 
-    private static async Task WaitAsync(HttpClient http, string operation, NativeComparisonExecutionOptions policy, CancellationToken token)
+    private static async Task<string> WaitAsync(HttpClient http, string operation, NativeComparisonExecutionOptions policy, CancellationToken token)
     {
         var deadline = TimeProvider.System.GetUtcNow() + policy.IndexBuildTimeout;
         while (true)
         {
             var ast = HelixDbProtocol.Node(HelixDbNativeTokens.TokenGetIndexOperation, new() { [HelixDbNativeTokens.TokenOperationId] = operation });
             using var response = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, false), false, policy, token).ConfigureAwait(false);
-            var status = Single(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows)).GetProperty(HelixDbNativeTokens.TokenStatus).GetString();
+            var observedOperation = Single(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows));
+            var status = observedOperation.GetProperty(HelixDbNativeTokens.TokenStatus).GetString();
             if (status == HelixDbNativeTokens.TokenSucceeded)
             {
-                return;
+                return observedOperation.GetRawText();
             }
 
             if (status is HelixDbNativeTokens.TokenBlocked or HelixDbNativeTokens.TokenAborted || TimeProvider.System.GetUtcNow() >= deadline)

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Targets/HelixDB/Execution/HelixDbIndexLifecycle.cs

@@ -1,11 +1,13 @@
+using Microsoft.Extensions.Options;
 using System.Collections.Immutable;
 using System.Runtime.CompilerServices;
 using System.Text.Json;
 using System.Text.Json.Nodes;
 
 namespace KeyLoad.Comparisons.Targets;
-internal sealed class HelixDbSession(HttpClient http, string label, int count, int depth, NativeComparisonExecutionOptions policy) : IComparisonSession
+internal sealed class HelixDbSession(HttpClient http, string label, int count, int depth, IOptions<NativeComparisonExecutionOptions> executionOptions) : IComparisonSession
 {
+    private NativeComparisonExecutionOptions Policy => executionOptions.Value;
     private const int EmptyResultCount = 0;
     private const int SingleResultCardinality = 1;
     public async Task<FoundDocument?> ReadAsync(BenchmarkDocument document, CancellationToken cancellationToken)
@@ -21,7 +23,7 @@ public async IAsyncEnumerable<FoundDocument> ReadCorpusAsync([EnumeratorCancella
         var seen = EmptyResultCount;
         while (true)
         {
-            using var response = await QueryAsync(HelixDbDocumentAst.Page(label, after, policy.ReadbackBatchCapacity), false, cancellationToken).ConfigureAwait(false);
+            using var response = await QueryAsync(HelixDbDocumentAst.Page(label, after, Policy.ReadbackBatchCapacity), false, cancellationToken).ConfigureAwait(false);
             var rows = HelixDbProtocol.Rows(response);
             if (rows.GetArrayLength() == EmptyResultCount)
             {
@@ -75,7 +77,7 @@ private async Task MutateAsync(Scenario scenario, BenchmarkDocument document, Ca
                 HelixDbProtocol.Entry(HelixDbProtocol.Node(HelixDbNativeTokens.TokenCount, new() { [HelixDbNativeTokens.TokenInput] = HelixDbDocumentAst.Lookup(label, document.Id) }), HelixDbNativeTokens.TokenAffected),
                 HelixDbProtocol.Entry(HelixDbProtocol.Node(HelixDbNativeTokens.TokenDrop, new() { [HelixDbNativeTokens.TokenInput] = HelixDbDocumentAst.Lookup(label, document.Id) }), HelixDbNativeTokens.TokenRemoved)
             };
-            using var result = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(entries, true, [HelixDbNativeTokens.TokenAffected]), true, policy, token).ConfigureAwait(false);
+            using var result = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(entries, true, [HelixDbNativeTokens.TokenAffected]), true, Policy, token).ConfigureAwait(false);
             RequireOne(result.RootElement.GetProperty(HelixDbNativeTokens.TokenAffected), scenario);
             return;
         }
@@ -89,7 +91,7 @@ private async Task MutateAsync(Scenario scenario, BenchmarkDocument document, Ca
         RequireOne(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows), scenario);
     }
 
-    private Task<JsonDocument> QueryAsync(JsonObject ast, bool write, CancellationToken token) => HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, write), write, policy, token);
+    private Task<JsonDocument> QueryAsync(JsonObject ast, bool write, CancellationToken token) => HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, write), write, Policy, token);
     private static FoundDocument Read(JsonElement row) => new(row.GetProperty(HelixDbNativeTokens.TokenId).GetString()!, row.GetProperty(HelixDbNativeTokens.TokenPayload).GetString()!);
     private static void RequireOne(JsonElement result, Scenario scenario)
     {

benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Targets/HelixDB/Execution/HelixDbSession.cs

@@ -17,11 +17,14 @@ public sealed class HelixDbTarget(HttpClient http, string runId, string image, I
     private const int SingleResultCardinality = 1;
     private const string SingleLocalWriterNoReplicationConfigured = "single local writer; no replication configured";
     private const string HELIXDATADIRPersistentDirectory = "HELIX_DATA_DIR persistent directory";
-    private readonly NativeComparisonExecutionOptions policy = executionOptions.Value.Validate();
+    private readonly IOptions<NativeComparisonExecutionOptions> execution = NativeComparisonExecutionOptions.Require(executionOptions);
+    private NativeComparisonExecutionOptions Policy => execution.Value;
     private readonly string label = HelixDbNativeTokens.TokenKeyLoadDoc + Guid.Parse(runId).ToString(HelixDbNativeTokens.TokenN);
     private int count;
     private int depth;
     private bool ownsData;
+    private bool ownsEqualityIndex;
+    private bool ownsRangeIndex;
     /// <inheritdoc/>
     public TargetProfile Profile { get; } = new(HelixDbNativeTokens.TokenHelixDB, V0PinnedNativeServerImage, OnePersistentNativeLocalWriter, XHelixAwaitDurableTrueNativeDiskFlush, CommittedNativeReadsAndDirectedGraphTraversal, POSTV2QueryOperationTree, IsolatedLocalServerNoAuthentication, image)
     {
@@ -39,16 +42,18 @@ public async Task InitializeAsync(IComparisonCorpus dataset, CancellationToken c
         count = dataset.Documents.Count;
         depth = dataset.Settings.GraphDepth;
         ownsData = true;
-        await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenId, range: false), policy, cancellationToken).ConfigureAwait(false);
-        await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenNumber, range: true), policy, cancellationToken).ConfigureAwait(false);
-        await HelixDbDocumentStorage.SeedAsync(http, label, dataset, policy, cancellationToken).ConfigureAwait(false);
+        await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenId, range: false), Policy, cancellationToken).ConfigureAwait(false);
+        ownsEqualityIndex = true;
+        await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenNumber, range: true), Policy, cancellationToken).ConfigureAwait(false);
+        ownsRangeIndex = true;
+        await HelixDbDocumentStorage.SeedAsync(http, label, dataset, Policy, cancellationToken).ConfigureAwait(false);
     }
 
     /// <inheritdoc/>
     public Task<IComparisonSession> OpenSessionAsync(CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-        return Task.FromResult<IComparisonSession>(new HelixDbSession(http, label, count, depth, policy));
+        return Task.FromResult<IComparisonSession>(new HelixDbSession(http, label, count, depth, execution));
     }
 
     /// <inheritdoc/>
@@ -58,8 +63,16 @@ public async ValueTask DisposeAsync()
         {
             if (ownsData)
             {
-                using var timeout = new CancellationTokenSource(policy.CleanupTimeout);
-                using var response = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(HelixDbProtocol.Node(HelixDbNativeTokens.TokenDrop, new() { [HelixDbNativeTokens.TokenInput] = HelixDbProtocol.Nodes(label) }), true), true, policy, timeout.Token).ConfigureAwait(false);
+                using var timeout = new CancellationTokenSource(Policy.CleanupTimeout);
+                if (ownsEqualityIndex)
+                {
+                    await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.DropIndex(label, HelixDbNativeTokens.TokenId, range: false), Policy, timeout.Token).ConfigureAwait(false);
+                }
+                if (ownsRangeIndex)
+                {
+                    await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.DropIndex(label, HelixDbNativeTokens.TokenNumber, range: true), Policy, timeout.Token).ConfigureAwait(false);
+                }
+                using var response = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(HelixDbProtocol.Node(HelixDbNativeTokens.TokenDrop, new() { [HelixDbNativeTokens.TokenInput] = HelixDbProtocol.Nodes(label) }), true), true, Policy, timeout.Token).ConfigureAwait(false);
             }
         }
         finally