Skip to content

Commit c8ab6ca

Browse files
KSemenenkoKSemenenko
committed
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.
1 parent 68a8660 commit c8ab6ca

109 files changed

Lines changed: 1807 additions & 585 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@ namespace KeyLoad.ComparisonHost.Features.BenchmarkComparisons;
99
/// <summary>Owns only one native target and tracks partial HTTP construction until ownership transfers.</summary>
1010
internal sealed class IsolatedHostTargetOwner(IOptions<NativeComparisonExecutionOptions> executionOptions) : IAsyncDisposable
1111
{
12-
private readonly NativeComparisonExecutionOptions policy = executionOptions.Value.Validate();
13-
internal IOptions<NativeComparisonExecutionOptions> ExecutionOptions => executionOptions;
12+
private readonly IOptions<NativeComparisonExecutionOptions> execution = NativeComparisonExecutionOptions.Require(executionOptions);
13+
private NativeComparisonExecutionOptions Policy => execution.Value;
14+
internal IOptions<NativeComparisonExecutionOptions> ExecutionOptions => execution;
1415
private readonly List<HttpClient> unownedClients = [];
1516
private IComparisonTarget? target;
1617
private IVectorComparisonTarget? vectorTarget;
@@ -118,7 +119,7 @@ public async ValueTask DisposeAsync()
118119
if (ownedVectorTarget is not null)
119120
{
120121
var cleanup = ownedVectorTarget.DisposeAsync().AsTask();
121-
await cleanup.WaitAsync(policy.CleanupTimeout);
122+
await cleanup.WaitAsync(Policy.CleanupTimeout);
122123
}
123124
}
124125
finally
@@ -136,7 +137,7 @@ private async Task DisposeTargetAsync(IComparisonTarget ownedTarget)
136137
var cleanup = ownedTarget.DisposeAsync().AsTask();
137138
try
138139
{
139-
await cleanup.WaitAsync(policy.CleanupTimeout);
140+
await cleanup.WaitAsync(Policy.CleanupTimeout);
140141
}
141142
catch (Exception)
142143
{

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
namespace KeyLoad.Comparisons;
2+
3+
/// <summary>Holds trusted isolated worker selectors and detects forbidden immutable-workload overrides.</summary>
4+
[ConfigurationOptions]
5+
public sealed class ComparisonWorkerSelectionOptions
6+
{
7+
/// <summary>Names the workflow selector section.</summary>
8+
public const string SectionName = "Benchmarks";
9+
10+
/// <summary>Gets or sets the canonical engine name.</summary>
11+
public string? Target { get; set; }
12+
13+
/// <summary>Gets or sets the actual native member count.</summary>
14+
public string? NodeCount { get; set; }
15+
16+
/// <summary>Gets or sets the exact workload scenario.</summary>
17+
public string? Scenario { get; set; }
18+
19+
/// <summary>Gets or sets the authenticated profile identifier.</summary>
20+
public string? EvidenceProfile { get; set; }
21+
22+
/// <summary>Gets or sets the optional immutable scale profile.</summary>
23+
public string? ScaleProfile { get; set; }
24+
25+
/// <summary>Gets or sets the optional immutable vector profile.</summary>
26+
public string? VectorProfile { get; set; }
27+
28+
/// <summary>Gets or sets the optional offered-rate cohort.</summary>
29+
public string? OpenLoopRate { get; set; }
30+
31+
/// <summary>Gets or sets the optional AppHost mode.</summary>
32+
public string? Profile { get; set; }
33+
34+
/// <summary>Gets or sets the document count override.</summary>
35+
public string? Documents { get; set; }
36+
37+
/// <summary>Gets or sets the operation count override.</summary>
38+
public string? Operations { get; set; }
39+
40+
/// <summary>Gets or sets the warmup override.</summary>
41+
public string? Warmup { get; set; }
42+
43+
/// <summary>Gets or sets the repetition override.</summary>
44+
public string? Repetitions { get; set; }
45+
46+
/// <summary>Gets or sets the concurrency override.</summary>
47+
public string? Concurrency { get; set; }
48+
49+
/// <summary>Gets or sets the payload size override.</summary>
50+
public string? PayloadBytes { get; set; }
51+
52+
/// <summary>Gets or sets the seed override.</summary>
53+
public string? Seed { get; set; }
54+
55+
/// <summary>Gets or sets the vector dimension override.</summary>
56+
public string? Dimensions { get; set; }
57+
58+
/// <summary>Gets or sets the neighbor count override.</summary>
59+
public string? TopK { get; set; }
60+
61+
/// <summary>Gets or sets the operation timeout override.</summary>
62+
public string? TimeoutSeconds { get; set; }
63+
64+
/// <summary>Gets or sets the graph vertex override.</summary>
65+
public string? GraphVertices { get; set; }
66+
67+
/// <summary>Gets or sets the graph fan-out override.</summary>
68+
public string? GraphFanOut { get; set; }
69+
70+
/// <summary>Gets or sets the graph depth override.</summary>
71+
public string? GraphDepth { get; set; }
72+
}

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,16 @@ public sealed class NativeComparisonExecutionOptions
3434
/// <summary>The interval between native index completion checks.</summary>
3535
public TimeSpan IndexPollInterval { get; set; }
3636

37+
/// <summary>Validates the injected wrapper before any native target is created.</summary>
38+
/// <param name="options">The centrally bound options.</param>
39+
/// <returns>The validated native options wrapper.</returns>
40+
public static IOptions<NativeComparisonExecutionOptions> Require(IOptions<NativeComparisonExecutionOptions> options)
41+
{
42+
ArgumentNullException.ThrowIfNull(options);
43+
options.Value.Validate();
44+
return options;
45+
}
46+
3747
/// <summary>Rejects omitted or inconsistent operational configuration.</summary>
3848
/// <returns>This validated policy.</returns>
3949
public NativeComparisonExecutionOptions Validate()

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

Lines changed: 0 additions & 19 deletions
This file was deleted.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ private static async Task<ReadOnlyMemory<byte>> ReadBodyAsync(HttpContent conten
5252
throw new ComparisonFailureException(LimitFailure);
5353
}
5454

55-
body.Write(buffer, EmptyResultCount, count);
55+
await body.WriteAsync(buffer.AsMemory(EmptyResultCount, count), token).ConfigureAwait(false);
5656
}
5757

5858
return body.GetBuffer().AsMemory(EmptyResultCount, checked((int)body.Length));

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ namespace KeyLoad.Comparisons;
66
/// <summary>Serializes and strictly reconstitutes one of the exact closed scaled profile identities.</summary>
77
public sealed class ScaledComparisonProfileJsonConverter : JsonConverter<ScaledComparisonProfile>
88
{
9+
private const int PropertyCount = 14;
10+
private const string InvalidShape = "Scaled profile shape is invalid.";
11+
private const string SettingsMismatch = "Scaled profile settings mismatch.";
912
private const string ConcurrencyProperty = "concurrency";
1013
private const string DimensionsProperty = "dimensions";
1114
private const string DocumentsProperty = "documents";
@@ -25,10 +28,10 @@ public override ScaledComparisonProfile Read(ref Utf8JsonReader reader, Type typ
2528
{
2629
using var document = JsonDocument.ParseValue(ref reader);
2730
var root = document.RootElement;
28-
if (root.ValueKind != JsonValueKind.Object || root.EnumerateObject().Count() != 14
31+
if (root.ValueKind != JsonValueKind.Object || root.EnumerateObject().Count() != PropertyCount
2932
|| !root.TryGetProperty(IdProperty, out var id) || id.ValueKind != JsonValueKind.String)
3033
{
31-
throw new JsonException("Scaled profile shape is invalid.");
34+
throw new JsonException(InvalidShape);
3235
}
3336
var profile = ScaledComparisonProfileParser.Parse(id.GetString()!);
3437
Validate(root, profile);
@@ -68,7 +71,7 @@ private static void Require(JsonElement root, string name, int expected)
6871
if (!root.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Number
6972
|| !value.TryGetInt32(out var actual) || actual != expected)
7073
{
71-
throw new JsonException("Scaled profile settings mismatch.");
74+
throw new JsonException(SettingsMismatch);
7275
}
7376
}
7477

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

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ namespace KeyLoad.Comparisons.Targets;
77
internal static class HelixDbIndexLifecycle
88
{
99
private const string ProviderNativeANNOpaqueTuning = "provider-native ANN; opaque tuning";
10+
private const string CompletedOperation = "; completed operation=";
1011
private const string CompletedReceipt = "; completed receipt=";
1112
private const int SingleResultCardinality = 1;
1213
private const int EmptyResultCount = 0;
@@ -24,8 +25,8 @@ internal static async Task<string> ExecuteAsync(HttpClient http, JsonObject defi
2425
}
2526

2627
var operation = receipt.GetProperty(HelixDbNativeTokens.TokenOperationId).GetString()!;
27-
await WaitAsync(http, operation, policy, token).ConfigureAwait(false);
28-
return receipt.GetRawText();
28+
var completion = await WaitAsync(http, operation, policy, token).ConfigureAwait(false);
29+
return receipt.GetRawText() + CompletedOperation + completion;
2930
}
3031

3132
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
4546
return new(VectorIndexKind.NativeAnn, definition.ToJsonString() + CompletedReceipt + receipt, parameters, watch.Elapsed.TotalMilliseconds);
4647
}
4748

48-
private static async Task WaitAsync(HttpClient http, string operation, NativeComparisonExecutionOptions policy, CancellationToken token)
49+
private static async Task<string> WaitAsync(HttpClient http, string operation, NativeComparisonExecutionOptions policy, CancellationToken token)
4950
{
5051
var deadline = TimeProvider.System.GetUtcNow() + policy.IndexBuildTimeout;
5152
while (true)
5253
{
5354
var ast = HelixDbProtocol.Node(HelixDbNativeTokens.TokenGetIndexOperation, new() { [HelixDbNativeTokens.TokenOperationId] = operation });
5455
using var response = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, false), false, policy, token).ConfigureAwait(false);
55-
var status = Single(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows)).GetProperty(HelixDbNativeTokens.TokenStatus).GetString();
56+
var observedOperation = Single(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows));
57+
var status = observedOperation.GetProperty(HelixDbNativeTokens.TokenStatus).GetString();
5658
if (status == HelixDbNativeTokens.TokenSucceeded)
5759
{
58-
return;
60+
return observedOperation.GetRawText();
5961
}
6062

6163
if (status is HelixDbNativeTokens.TokenBlocked or HelixDbNativeTokens.TokenAborted || TimeProvider.System.GetUtcNow() >= deadline)

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1+
using Microsoft.Extensions.Options;
12
using System.Collections.Immutable;
23
using System.Runtime.CompilerServices;
34
using System.Text.Json;
45
using System.Text.Json.Nodes;
56

67
namespace KeyLoad.Comparisons.Targets;
7-
internal sealed class HelixDbSession(HttpClient http, string label, int count, int depth, NativeComparisonExecutionOptions policy) : IComparisonSession
8+
internal sealed class HelixDbSession(HttpClient http, string label, int count, int depth, IOptions<NativeComparisonExecutionOptions> executionOptions) : IComparisonSession
89
{
10+
private NativeComparisonExecutionOptions Policy => executionOptions.Value;
911
private const int EmptyResultCount = 0;
1012
private const int SingleResultCardinality = 1;
1113
public async Task<FoundDocument?> ReadAsync(BenchmarkDocument document, CancellationToken cancellationToken)
@@ -21,7 +23,7 @@ public async IAsyncEnumerable<FoundDocument> ReadCorpusAsync([EnumeratorCancella
2123
var seen = EmptyResultCount;
2224
while (true)
2325
{
24-
using var response = await QueryAsync(HelixDbDocumentAst.Page(label, after, policy.ReadbackBatchCapacity), false, cancellationToken).ConfigureAwait(false);
26+
using var response = await QueryAsync(HelixDbDocumentAst.Page(label, after, Policy.ReadbackBatchCapacity), false, cancellationToken).ConfigureAwait(false);
2527
var rows = HelixDbProtocol.Rows(response);
2628
if (rows.GetArrayLength() == EmptyResultCount)
2729
{
@@ -75,7 +77,7 @@ private async Task MutateAsync(Scenario scenario, BenchmarkDocument document, Ca
7577
HelixDbProtocol.Entry(HelixDbProtocol.Node(HelixDbNativeTokens.TokenCount, new() { [HelixDbNativeTokens.TokenInput] = HelixDbDocumentAst.Lookup(label, document.Id) }), HelixDbNativeTokens.TokenAffected),
7678
HelixDbProtocol.Entry(HelixDbProtocol.Node(HelixDbNativeTokens.TokenDrop, new() { [HelixDbNativeTokens.TokenInput] = HelixDbDocumentAst.Lookup(label, document.Id) }), HelixDbNativeTokens.TokenRemoved)
7779
};
78-
using var result = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(entries, true, [HelixDbNativeTokens.TokenAffected]), true, policy, token).ConfigureAwait(false);
80+
using var result = await HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(entries, true, [HelixDbNativeTokens.TokenAffected]), true, Policy, token).ConfigureAwait(false);
7981
RequireOne(result.RootElement.GetProperty(HelixDbNativeTokens.TokenAffected), scenario);
8082
return;
8183
}
@@ -89,7 +91,7 @@ private async Task MutateAsync(Scenario scenario, BenchmarkDocument document, Ca
8991
RequireOne(response.RootElement.GetProperty(HelixDbNativeTokens.TokenRows), scenario);
9092
}
9193

92-
private Task<JsonDocument> QueryAsync(JsonObject ast, bool write, CancellationToken token) => HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, write), write, policy, token);
94+
private Task<JsonDocument> QueryAsync(JsonObject ast, bool write, CancellationToken token) => HelixDbProtocol.QueryAsync(http, HelixDbProtocol.Batch(ast, write), write, Policy, token);
9395
private static FoundDocument Read(JsonElement row) => new(row.GetProperty(HelixDbNativeTokens.TokenId).GetString()!, row.GetProperty(HelixDbNativeTokens.TokenPayload).GetString()!);
9496
private static void RequireOne(JsonElement result, Scenario scenario)
9597
{

‎benchmarks/KeyLoad.Comparisons/Features/BenchmarkComparisons/Targets/HelixDB/Execution/HelixDbTarget.cs‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,14 @@ public sealed class HelixDbTarget(HttpClient http, string runId, string image, I
1717
private const int SingleResultCardinality = 1;
1818
private const string SingleLocalWriterNoReplicationConfigured = "single local writer; no replication configured";
1919
private const string HELIXDATADIRPersistentDirectory = "HELIX_DATA_DIR persistent directory";
20-
private readonly NativeComparisonExecutionOptions policy = executionOptions.Value.Validate();
20+
private readonly IOptions<NativeComparisonExecutionOptions> execution = NativeComparisonExecutionOptions.Require(executionOptions);
21+
private NativeComparisonExecutionOptions Policy => execution.Value;
2122
private readonly string label = HelixDbNativeTokens.TokenKeyLoadDoc + Guid.Parse(runId).ToString(HelixDbNativeTokens.TokenN);
2223
private int count;
2324
private int depth;
2425
private bool ownsData;
26+
private bool ownsEqualityIndex;
27+
private bool ownsRangeIndex;
2528
/// <inheritdoc/>
2629
public TargetProfile Profile { get; } = new(HelixDbNativeTokens.TokenHelixDB, V0PinnedNativeServerImage, OnePersistentNativeLocalWriter, XHelixAwaitDurableTrueNativeDiskFlush, CommittedNativeReadsAndDirectedGraphTraversal, POSTV2QueryOperationTree, IsolatedLocalServerNoAuthentication, image)
2730
{
@@ -39,16 +42,18 @@ public async Task InitializeAsync(IComparisonCorpus dataset, CancellationToken c
3942
count = dataset.Documents.Count;
4043
depth = dataset.Settings.GraphDepth;
4144
ownsData = true;
42-
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenId, range: false), policy, cancellationToken).ConfigureAwait(false);
43-
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenNumber, range: true), policy, cancellationToken).ConfigureAwait(false);
44-
await HelixDbDocumentStorage.SeedAsync(http, label, dataset, policy, cancellationToken).ConfigureAwait(false);
45+
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenId, range: false), Policy, cancellationToken).ConfigureAwait(false);
46+
ownsEqualityIndex = true;
47+
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.Index(label, HelixDbNativeTokens.TokenNumber, range: true), Policy, cancellationToken).ConfigureAwait(false);
48+
ownsRangeIndex = true;
49+
await HelixDbDocumentStorage.SeedAsync(http, label, dataset, Policy, cancellationToken).ConfigureAwait(false);
4550
}
4651

4752
/// <inheritdoc/>
4853
public Task<IComparisonSession> OpenSessionAsync(CancellationToken cancellationToken)
4954
{
5055
cancellationToken.ThrowIfCancellationRequested();
51-
return Task.FromResult<IComparisonSession>(new HelixDbSession(http, label, count, depth, policy));
56+
return Task.FromResult<IComparisonSession>(new HelixDbSession(http, label, count, depth, execution));
5257
}
5358

5459
/// <inheritdoc/>
@@ -58,8 +63,16 @@ public async ValueTask DisposeAsync()
5863
{
5964
if (ownsData)
6065
{
61-
using var timeout = new CancellationTokenSource(policy.CleanupTimeout);
62-
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);
66+
using var timeout = new CancellationTokenSource(Policy.CleanupTimeout);
67+
if (ownsEqualityIndex)
68+
{
69+
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.DropIndex(label, HelixDbNativeTokens.TokenId, range: false), Policy, timeout.Token).ConfigureAwait(false);
70+
}
71+
if (ownsRangeIndex)
72+
{
73+
await HelixDbIndexLifecycle.ExecuteAsync(http, HelixDbDocumentAst.DropIndex(label, HelixDbNativeTokens.TokenNumber, range: true), Policy, timeout.Token).ConfigureAwait(false);
74+
}
75+
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);
6376
}
6477
}
6578
finally

0 commit comments

Comments
 (0)