Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Claude Perf optimization M3.

Yuechen Li335dfb07df97
diff --git a/Aetheris.Web.Perf/Aetheris.Web.Perf.csproj b/Aetheris.Web.Perf/Aetheris.Web.Perf.csproj
index b16a2382..c330b88e 100644
--- a/Aetheris.Web.Perf/Aetheris.Web.Perf.csproj
+++ b/Aetheris.Web.Perf/Aetheris.Web.Perf.csproj
@@ -11,8 +11,10 @@
<ItemGroup>
<ProjectReference Include="..\Aetheris.Kernel.Firmament\Aetheris.Kernel.Firmament.csproj" />
<Compile Include="..\Aetheris.Web.Runtime\Program.cs" Link="WebProgram.cs" />
+ <Compile Include="..\Aetheris.Web.Runtime\WebResponseBridge.cs" Link="WebResponseBridge.cs" />
<Compile Include="PerfProgram.cs" />
<Compile Include="ShowcasePerf.cs" />
<Compile Include="CompareStep.cs" />
+ <Compile Include="VerifyBridge.cs" />
</ItemGroup>
</Project>
diff --git a/Aetheris.Web.Perf/PerfProgram.cs b/Aetheris.Web.Perf/PerfProgram.cs
index 3a5e8bbc..4afd579e 100644
--- a/Aetheris.Web.Perf/PerfProgram.cs
+++ b/Aetheris.Web.Perf/PerfProgram.cs
@@ -10,6 +10,7 @@ public static class PerfProgram
{
if (args.Length > 0 && args[0] == "showcase") return ShowcasePerf.Run(args[1..]);
if (args.Length > 0 && args[0] == "compare-step") return CompareStep.Run(args[1..]);
+ if (args.Length > 0 && args[0] == "verify-bridge") return VerifyBridge.Run(args[1..]);
if (args.Length != 1) { Console.Error.WriteLine("Usage: Aetheris.Web.Perf <helix-fixture> | Aetheris.Web.Perf showcase --help | Aetheris.Web.Perf compare-step <a.step> <b.step>"); return 2; }
var source = File.ReadAllText(args[0]);
var variants = new[] { ("helix-1", source), ("helix-2", source.Replace("Turns: 1", "Turns: 2", StringComparison.Ordinal)),
diff --git a/Aetheris.Web.Perf/VerifyBridge.cs b/Aetheris.Web.Perf/VerifyBridge.cs
new file mode 100644
index 00000000..a7cfbaa8
--- /dev/null
+++ b/Aetheris.Web.Perf/VerifyBridge.cs
@@ -0,0 +1,159 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace Aetheris.Web.Perf;
+
+/// <summary>
+/// BUILD-PERF-M3: the bridge (binary arrays + retained definitions) must deliver exactly what the
+/// legacy JSON response delivers. A legacy session and a bridged session build the same project
+/// through cold build, no-change rebuild and root-comment edit; each bridged model is
+/// reconstructed the way the SDK does it and compared with the legacy model.
+/// </summary>
+internal static class VerifyBridge
+{
+ public static int Run(string[] args)
+ {
+ if (args.Length != 2) { Console.Error.WriteLine("Usage: Aetheris.Web.Perf verify-bridge <project-directory|file> <root>"); return 2; }
+ var (documents, root) = Load(args[0], args[1]);
+ var projectDocuments = documents.Count > 1 ? documents : null;
+ var failures = 0;
+ JsonNode? legacySession = null, bridgedSession = null;
+ JsonObject? previousBridged = null;
+ var steps = new (string Name, Func<Dictionary<string, string>, object> Request)[]
+ {
+ ("cold build", d => new { operation = "compile", source = d[root], sourceName = root, projectDocuments = d.Count > 1 ? d : null }),
+ ("no-change rebuild", _ => new { operation = "rebuild" }),
+ ("root comment edit", _ => new { operation = "rebuild" }),
+ };
+ var current = new Dictionary<string, string>(documents, StringComparer.Ordinal);
+ foreach (var (name, request) in steps)
+ {
+ if (name == "root comment edit")
+ {
+ current[root] += "\n// verify-bridge\n";
+ foreach (var session in new[] { legacySession, bridgedSession })
+ Call(new { operation = "setSource", sessionId = session!.GetValue<string>(), source = current[root], sourceName = root, projectDocuments = current.Count > 1 ? current : null }, bridged: false);
+ }
+ var legacy = Call(WithSession(request(current), legacySession), bridged: false);
+ var (bridgedRaw, binary) = CallBridged(WithSession(request(current), bridgedSession));
+ var bridged = Reconstruct(bridgedRaw, binary, previousBridged, out var retained, out var binaryArrays);
+ legacySession ??= legacy["result"]!["model"]!["id"]!.DeepClone();
+ bridgedSession ??= bridged["result"]!["model"]!["id"]!.DeepClone();
+ var expected = Comparable(legacy); var actual = Comparable(bridged);
+ var equal = JsonNode.DeepEquals(expected, actual);
+ Console.WriteLine($"{name,-18} legacy {Size(legacy.ToJsonString())} · bridged {Size(bridgedRaw.ToJsonString())} JSON + {Size(binary.Length)} binary · " +
+ $"{binaryArrays} binary arrays · {retained} retained definitions · {(equal ? "identical" : "DIFFERENT")}");
+ if (!equal) { failures++; Report(expected, actual, "model"); }
+ previousBridged = bridged["result"]!["model"]!.AsObject();
+ }
+ Console.WriteLine(failures == 0 ? "Bridge delivers exactly the legacy model." : $"{failures} step(s) differ.");
+ return failures == 0 ? 0 : 1;
+ }
+
+ private static (Dictionary<string, string>, string) Load(string path, string root)
+ {
+ if (File.Exists(path)) return (new(StringComparer.Ordinal) { [root] = File.ReadAllText(path).Replace("\r\n", "\n") }, root);
+ return (Directory.GetFiles(path).Where(f => f.EndsWith(".firmament", StringComparison.Ordinal) || f.EndsWith(".firmasm", StringComparison.Ordinal))
+ .ToDictionary(Path.GetFileName, f => File.ReadAllText(f).Replace("\r\n", "\n"), StringComparer.Ordinal)!, root);
+ }
+
+ private static object WithSession(object request, JsonNode? session)
+ {
+ var node = JsonSerializer.SerializeToNode(request)!.AsObject();
+ if (session is not null) node["sessionId"] = session.DeepClone();
+ return node;
+ }
+
+ private static JsonObject Call(object request, bool bridged)
+ {
+ var node = JsonSerializer.SerializeToNode(request)!.AsObject();
+ if (bridged) node["bridge"] = 1;
+ var response = JsonNode.Parse(Aetheris.Web.Runtime.Program.Invoke(node.ToJsonString()))!.AsObject();
+ if (response["ok"]?.GetValue<bool>() != true) throw new InvalidOperationException(response.ToJsonString()[..Math.Min(600, response.ToJsonString().Length)]);
+ return response;
+ }
+
+ private static (JsonObject Response, byte[] Binary) CallBridged(object request)
+ {
+ var response = Call(request, bridged: true);
+ return (response, Aetheris.Web.Runtime.Program.TakeBinary());
+ }
+
+ /// <summary>What the SDK does: binary placeholders become arrays, retained definitions are
+ /// taken from the previous model's definitions by id.</summary>
+ private static JsonObject Reconstruct(JsonObject response, byte[] binary, JsonObject? previous, out int retained, out int arrays)
+ {
+ var copy = response.DeepClone().AsObject();
+ var counts = new int[2];
+ JsonNode? Revive(JsonNode? node)
+ {
+ switch (node)
+ {
+ case JsonObject obj when obj["$binary"] is { } type:
+ counts[1]++;
+ var offset = obj["byteOffset"]!.GetValue<int>(); var length = obj["length"]!.GetValue<int>();
+ var array = new JsonArray();
+ if (type.GetValue<string>() == "f64")
+ for (var i = 0; i < length; i++) array.Add(BitConverter.ToDouble(binary, offset + 8 * i));
+ else
+ for (var i = 0; i < length; i++) array.Add(BitConverter.ToInt32(binary, offset + 4 * i));
+ return array;
+ case JsonObject obj:
+ foreach (var key in obj.Select(pair => pair.Key).ToArray()) obj[key] = Revive(obj[key]?.DeepClone());
+ return obj;
+ case JsonArray list:
+ var revived = new JsonArray();
+ foreach (var item in list) revived.Add(Revive(item?.DeepClone()));
+ return revived;
+ default: return node;
+ }
+ }
+ var revivedResponse = Revive(copy)!.AsObject();
+ if (revivedResponse["result"]?["model"]?["mesh"]?["definitions"] is JsonArray definitions)
+ {
+ var kept = (previous?["mesh"]?["definitions"] as JsonArray)?.ToDictionary(d => d!["id"]!.GetValue<string>(), d => d!) ?? [];
+ for (var i = 0; i < definitions.Count; i++)
+ if (definitions[i]?["retained"]?.GetValue<bool>() == true)
+ {
+ counts[0]++;
+ var id = definitions[i]!["id"]!.GetValue<string>();
+ definitions[i] = kept.TryGetValue(id, out var definition) ? definition.DeepClone()
+ : throw new InvalidOperationException($"Retained definition {id} is not in the previous model.");
+ }
+ }
+ retained = counts[0]; arrays = counts[1];
+ return revivedResponse;
+ }
+
+ /// <summary>The model without its session id and timings (which legitimately differ).</summary>
+ private static JsonNode Comparable(JsonObject response)
+ {
+ var model = response["result"]!["model"]!.DeepClone().AsObject();
+ var session = model["id"]!.GetValue<string>();
+ model.Remove("id"); model.Remove("timings");
+ // The part path embeds the session id in entity ids; two sessions legitimately differ there.
+ var text = System.Text.RegularExpressions.Regex.Replace(model.ToJsonString(),
+ $@"(?<![\w-]){System.Text.RegularExpressions.Regex.Escape(session)}(?!\d)", "<session>");
+ return JsonNode.Parse(text)!;
+ }
+
+ private static void Report(JsonNode? expected, JsonNode? actual, string path, int budget = 5)
+ {
+ if (JsonNode.DeepEquals(expected, actual)) return;
+ if (expected is JsonObject a && actual is JsonObject b)
+ {
+ foreach (var key in a.Select(p => p.Key).Union(b.Select(p => p.Key))) Report(a[key], b[key], $"{path}.{key}", budget);
+ return;
+ }
+ if (expected is JsonArray x && actual is JsonArray y && x.Count == y.Count)
+ {
+ for (var i = 0; i < x.Count && budget > 0; i++) if (!JsonNode.DeepEquals(x[i], y[i])) { Report(x[i], y[i], $"{path}[{i}]", 1); budget--; }
+ return;
+ }
+ Console.Error.WriteLine($" {path}: {Short(expected)} vs {Short(actual)}");
+ }
+
+ private static string Short(JsonNode? node) { var text = node?.ToJsonString() ?? "null"; return text.Length > 120 ? text[..120] + "…" : text; }
+ private static string Size(long bytes) => bytes >= 1 << 20 ? $"{bytes / (double)(1 << 20):0.0} MB" : $"{bytes / 1024.0:0} KB";
+ private static string Size(string text) => Size(System.Text.Encoding.UTF8.GetByteCount(text));
+}
diff --git a/Aetheris.Web.Perf/build-perf-budgets.json b/Aetheris.Web.Perf/build-perf-budgets.json
index bf2c86dd..d110fa59 100644
--- a/Aetheris.Web.Perf/build-perf-budgets.json
+++ b/Aetheris.Web.Perf/build-perf-budgets.json
@@ -2,31 +2,31 @@
"schema": "aetheris/build-perf-budgets/m0",
"note": "Machine-independent fields always gate; *Milliseconds fields gate only with --check-time on the recorded machine.",
"recordedOn": "vm \u00b7 2 CPU \u00b7 Unix 6.18.44.114",
- "recordedCommit": "2b3abbbf893a + BUILD-PERF-M0/M1 working tree",
+ "recordedCommit": "59d785c + BUILD-PERF-M3 working tree",
"projects": {
"bracket": {
"stepDataSha256": "c3323aa5717fbd198c6148ab082623f0f5920c42487c6dd5f398da4abd2d4170",
"meshSha256": "b0ec1fb0d1d40af0e6b13fe9fa1ddd38167ebde5f3f3fd946eeaac4ba97509f9",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 679.6,
- "responseBytes": 51765,
- "allocatedBytes": 6383736
+ "invokeMilliseconds": 739.5,
+ "responseBytes": 29435,
+ "allocatedBytes": 6275824
},
"warm": {
- "invokeMilliseconds": 34.4,
- "responseBytes": 51746,
- "allocatedBytes": 3639336
+ "invokeMilliseconds": 32.9,
+ "responseBytes": 29413,
+ "allocatedBytes": 3594672
},
"noChangeRebuild": {
- "invokeMilliseconds": 32.2,
- "responseBytes": 51668,
- "allocatedBytes": 3538208
+ "invokeMilliseconds": 31.4,
+ "responseBytes": 29338,
+ "allocatedBytes": 3493480
},
"rootCommentEdit": {
- "invokeMilliseconds": 32.8,
- "responseBytes": 51703,
- "allocatedBytes": 3540192
+ "invokeMilliseconds": 32.9,
+ "responseBytes": 29369,
+ "allocatedBytes": 3495448
}
},
"bolt": {
@@ -34,29 +34,29 @@
"meshSha256": "aa9262734e2c79801a33b60f318d646b7a81aebda0b2bea9c0e711b775f835a6",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 6059.3,
- "responseBytes": 13899860,
- "allocatedBytes": 1935725472
+ "invokeMilliseconds": 5584.9,
+ "responseBytes": 6952210,
+ "allocatedBytes": 1905403056
},
"warm": {
- "invokeMilliseconds": 3634.7,
- "responseBytes": 13899844,
- "allocatedBytes": 1884732616
+ "invokeMilliseconds": 3722.3,
+ "responseBytes": 6952197,
+ "allocatedBytes": 1870209832
},
"noChangeRebuild": {
- "invokeMilliseconds": 3391.7,
- "responseBytes": 13899795,
- "allocatedBytes": 1882444560
+ "invokeMilliseconds": 3305.3,
+ "responseBytes": 6952145,
+ "allocatedBytes": 1869492264
},
"leafCommentEdit": {
- "invokeMilliseconds": 3052.2,
- "responseBytes": 13899791,
- "allocatedBytes": 1882094152
+ "invokeMilliseconds": 2990.6,
+ "responseBytes": 6952139,
+ "allocatedBytes": 1869110760
},
"rootCommentEdit": {
- "invokeMilliseconds": 3152.8,
- "responseBytes": 13899824,
- "allocatedBytes": 1882099592
+ "invokeMilliseconds": 3149.3,
+ "responseBytes": 6952170,
+ "allocatedBytes": 1869112208
}
},
"atlas": {
@@ -64,33 +64,33 @@
"meshSha256": "49fe7e6ef3adce069b21582e99cb1f16876aa10d8da9b13b4b4e029a8b6c2c0b",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 9150.4,
- "responseBytes": 3469581,
- "allocatedBytes": 3406553272,
+ "invokeMilliseconds": 9105.4,
+ "responseBytes": 1768201,
+ "allocatedBytes": 3398890448,
"reusedDefinitions": 0
},
"warm": {
- "invokeMilliseconds": 3846.3,
- "responseBytes": 3469453,
- "allocatedBytes": 3386982160,
+ "invokeMilliseconds": 3824.6,
+ "responseBytes": 1768079,
+ "allocatedBytes": 3377597592,
"reusedDefinitions": 0
},
"noChangeRebuild": {
- "invokeMilliseconds": 90,
- "responseBytes": 3426152,
- "allocatedBytes": 37745824,
+ "invokeMilliseconds": 85.3,
+ "responseBytes": 1724775,
+ "allocatedBytes": 34339800,
"reusedDefinitions": 24
},
"leafCommentEdit": {
- "invokeMilliseconds": 1073.6,
- "responseBytes": 3450508,
- "allocatedBytes": 479328584,
+ "invokeMilliseconds": 938.6,
+ "responseBytes": 1749125,
+ "allocatedBytes": 475902936,
"reusedDefinitions": 2
},
"rootCommentEdit": {
- "invokeMilliseconds": 100.1,
- "responseBytes": 3426184,
- "allocatedBytes": 37359912,
+ "invokeMilliseconds": 99.4,
+ "responseBytes": 1724800,
+ "allocatedBytes": 33935376,
"reusedDefinitions": 24
}
},
@@ -99,39 +99,39 @@
"meshSha256": "700ae75e20a1c49685e3d6478b4ff7e714cb28bd36491caf786c63c591a6a2c6",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 23141.1,
- "responseBytes": 18058270,
- "allocatedBytes": 9646906056,
+ "invokeMilliseconds": 23600.6,
+ "responseBytes": 9095710,
+ "allocatedBytes": 9593820240,
"reusedDefinitions": 0
},
"warm": {
- "invokeMilliseconds": 13030.1,
- "responseBytes": 18057812,
- "allocatedBytes": 9543507448,
+ "invokeMilliseconds": 12679.1,
+ "responseBytes": 9095289,
+ "allocatedBytes": 9522156512,
"reusedDefinitions": 0
},
"noChangeRebuild": {
- "invokeMilliseconds": 292.4,
- "responseBytes": 17969484,
- "allocatedBytes": 152488328,
+ "invokeMilliseconds": 272.6,
+ "responseBytes": 9006961,
+ "allocatedBytes": 134558096,
"reusedDefinitions": 56
},
"leafValueEdit": {
- "invokeMilliseconds": 3713.6,
- "responseBytes": 18033417,
- "allocatedBytes": 2351724208,
+ "invokeMilliseconds": 3860.7,
+ "responseBytes": 9070832,
+ "allocatedBytes": 2333644672,
"reusedDefinitions": 4
},
"leafCommentEdit": {
- "invokeMilliseconds": 5833,
- "responseBytes": 17970980,
- "allocatedBytes": 4286504152,
+ "invokeMilliseconds": 5863.5,
+ "responseBytes": 9008448,
+ "allocatedBytes": 4266198336,
"reusedDefinitions": 55
},
"rootCommentEdit": {
- "invokeMilliseconds": 353.2,
- "responseBytes": 17969518,
- "allocatedBytes": 152070432,
+ "invokeMilliseconds": 245.2,
+ "responseBytes": 9006983,
+ "allocatedBytes": 134139752,
"reusedDefinitions": 56
}
},
@@ -140,29 +140,29 @@
"meshSha256": "ce00e129709c10a86151b4bea6f000947cf1c51e0bb4a226b67aea8f3d54a15a",
"rebuildMatchesCold": true,
"cold": {
- "invokeMilliseconds": 5324.4,
- "responseBytes": 5288284,
- "allocatedBytes": 675499016
+ "invokeMilliseconds": 5516,
+ "responseBytes": 2698128,
+ "allocatedBytes": 661968768
},
"warm": {
- "invokeMilliseconds": 3133.1,
- "responseBytes": 5288246,
- "allocatedBytes": 648470768
+ "invokeMilliseconds": 2593.5,
+ "responseBytes": 2697961,
+ "allocatedBytes": 643069968
},
"noChangeRebuild": {
- "invokeMilliseconds": 755.4,
- "responseBytes": 5217160,
- "allocatedBytes": 186496320
+ "invokeMilliseconds": 593.8,
+ "responseBytes": 2626917,
+ "allocatedBytes": 177762208
},
"leafCommentEdit": {
- "invokeMilliseconds": 1536.3,
- "responseBytes": 5264742,
- "allocatedBytes": 592901384
+ "invokeMilliseconds": 1691.6,
+ "responseBytes": 2674512,
+ "allocatedBytes": 587303904
},
"rootCommentEdit": {
- "invokeMilliseconds": 441.6,
- "responseBytes": 5217187,
- "allocatedBytes": 185895752
+ "invokeMilliseconds": 490.6,
+ "responseBytes": 2626928,
+ "allocatedBytes": 180846088
}
}
}
diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.cs
index 2730eb4d..9d4c63e5 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -20,6 +20,17 @@ public static partial class Program
{
private const string ContractVersion = "aetheris/web-editor-contract/1";
private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
+ private static readonly JsonSerializerOptions BridgeOptions = WebResponseBridge.Options(JsonOptions);
+ private static byte[] _pendingBinary = [];
+
+ /// <summary>The binary payload of the last bridge-mode response (empty when none); taken once.</summary>
+ [JSExport]
+ public static byte[] TakeBinary()
+ {
+ var binary = _pendingBinary;
+ _pendingBinary = [];
+ return binary;
+ }
private static readonly Dictionary<string, WebModelSession> Sessions = new(StringComparer.Ordinal);
private static int _nextSession;
@@ -32,6 +43,7 @@ public static partial class Program
{
var request = JsonSerializer.Deserialize<WebRequest>(requestJson, JsonOptions)
?? throw new WebRuntimeException("invalid-request", "The runtime request was empty.");
+ _pendingBinary = [];
if (request.Performance) BuildPerfTrace.Start();
object? result = request.Operation switch
{
@@ -54,7 +66,7 @@ public static partial class Program
"disposeRuntime" => DisposeRuntime(),
_ => throw new WebRuntimeException("unknown-operation", $"Unknown runtime operation '{request.Operation}'.")
};
- var response = JsonSerializer.Serialize(new { ok = true, result }, JsonOptions);
+ var response = request.Bridge >= 1 ? SerializeBridged(request, result) : JsonSerializer.Serialize(new { ok = true, result }, JsonOptions);
BuildPerfTrace.Stop();
return response;
}
@@ -230,7 +242,26 @@ public static partial class Program
string? SourceName = null, string? PropertyId = null, WebPropertyValue? Value = null,
string? SourceRevision = null, int? Offset = null, string? ConstructSemanticId = null,
string? FieldId = null, FirmamentProjectedValue? FieldValue = null, int? BuildRevision = null,
- bool Performance = false, IReadOnlyDictionary<string, string>? ProjectDocuments = null, string? ProjectRoot = null);
+ bool Performance = false, IReadOnlyDictionary<string, string>? ProjectDocuments = null, string? ProjectRoot = null,
+ int? Bridge = null);
+
+ /// <summary>
+ /// BUILD-PERF-M3 response bridge (request <c>bridge: 1</c>, sent by the SDK). Large numeric arrays
+ /// leave as one binary buffer (<see cref="TakeBinary"/>); a rebuild references mesh definitions the
+ /// session's previous response already delivered instead of serializing them again.
+ /// </summary>
+ private static string SerializeBridged(WebRequest request, object? result)
+ {
+ var owner = (result as WebBuildResult) is { Success: true, Owner: WebModelSession session } ? session : null;
+ var bridge = new WebResponseBridge(request.Operation == "rebuild" && owner is not null ? owner.SentDefinitions : null);
+ WebResponseBridge.Current = bridge;
+ string response;
+ try { response = JsonSerializer.Serialize(new { ok = true, result }, BridgeOptions); }
+ finally { WebResponseBridge.Current = null; }
+ _pendingBinary = bridge.ToArray();
+ owner?.MarkDelivered();
+ return response;
+ }
private sealed class WebRuntimeException(string code, string message) : Exception(message)
{
@@ -253,6 +284,10 @@ public static partial class Program
public string Id { get; } = id;
public string Name => Path.GetFileNameWithoutExtension(_sourceName);
public int Revision { get; private set; }
+ private object[] _currentDefinitions = [];
+ /// <summary>Definitions of the last snapshot a bridged response delivered to the client.</summary>
+ internal HashSet<object> SentDefinitions { get; private set; } = new(ReferenceEqualityComparer.Instance);
+ internal void MarkDelivered() => SentDefinitions = new(_currentDefinitions, ReferenceEqualityComparer.Instance);
private string? _stepText;
private Func<string>? _stepWriter;
/// <summary>STEP of the current build. Assemblies write it on first request (BUILD-PERF-M1);
@@ -379,7 +414,10 @@ public static partial class Program
tree = compiled.Tree, properties = _properties, mesh = compiled.Mesh,
diagnostics = compiled.Diagnostics, changes, timings
};
- return compiled with { Revision = Revision, Model = _lastSnapshot, Changes = changes, StepText = null, StepWriter = null };
+ _currentDefinitions = compiled.Mesh is AssemblyDisplayMeshDocument document ? document.Definitions.Cast<object>().ToArray() : [];
+ // The snapshot carries tree, mesh and entity ids; the response does not repeat them.
+ return compiled with { Revision = Revision, Model = _lastSnapshot, Changes = changes, StepText = null, StepWriter = null,
+ Tree = null, Mesh = null, EntityIds = null, Owner = this };
}
private WebBuildResult CompilePart(string effective, List<WebProperty> properties)
@@ -687,6 +725,8 @@ internal sealed record WebBuildResult(bool Success, int Revision, object? Model,
object? Tree = null, object? Mesh = null, IReadOnlyList<string>? EntityIds = null, object? Timings = null, object? Changes = null, string? StepText = null,
IReadOnlyList<FirmamentConstructProjection>? Projections = null, double CompileMilliseconds = 0, double MeshMilliseconds = 0)
{
+ /// <summary>The session that produced this build; never serialized.</summary>
+ [System.Text.Json.Serialization.JsonIgnore] public object? Owner { get; init; }
/// <summary>Writes the STEP text on first request; never serialized.</summary>
[System.Text.Json.Serialization.JsonIgnore] public Func<string>? StepWriter { get; init; }
public static WebBuildResult Failed(IReadOnlyList<WebDiagnostic> diagnostics, double compileMs) => new(false, 0, null, diagnostics, false, Timings: new { compileMilliseconds = compileMs }, CompileMilliseconds: compileMs);
diff --git a/Aetheris.Web.Runtime/WebResponseBridge.cs b/Aetheris.Web.Runtime/WebResponseBridge.cs
new file mode 100644
index 00000000..7d02aa75
--- /dev/null
+++ b/Aetheris.Web.Runtime/WebResponseBridge.cs
@@ -0,0 +1,118 @@
+using System.Runtime.InteropServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Aetheris.Kernel.Firmament.Assembly;
+
+namespace Aetheris.Web.Runtime;
+
+/// <summary>
+/// BUILD-PERF-M3: state of one bridge-mode response. Numeric arrays of at least
+/// <see cref="BinaryThreshold"/> elements are written to one little-endian binary buffer,
+/// 8-byte aligned, and replaced in the JSON by <c>{"$binary":"f64"|"i32","byteOffset":o,"length":n}</c>.
+/// Mesh definitions in <see cref="Retained"/> (the very objects the session's previous response
+/// delivered) are written as <c>{"id","identity","retained":true}</c>; the SDK substitutes the
+/// definition it already holds. Values are bit-identical to the JSON path.
+/// </summary>
+internal sealed class WebResponseBridge(IReadOnlySet<object>? retained)
+{
+ internal const int BinaryThreshold = 64;
+ [ThreadStatic] internal static WebResponseBridge? Current;
+
+ private readonly MemoryStream binary = new();
+ internal IReadOnlySet<object>? Retained { get; } = retained;
+
+ internal long Append(ReadOnlySpan<byte> bytes)
+ {
+ while (binary.Length % 8 != 0) binary.WriteByte(0);
+ var offset = binary.Length;
+ binary.Write(bytes);
+ return offset;
+ }
+
+ internal byte[] ToArray() => binary.Length == 0 ? [] : binary.ToArray();
+
+ internal static JsonSerializerOptions Options(JsonSerializerOptions baseline)
+ {
+ var arrays = new JsonSerializerOptions(baseline);
+ arrays.Converters.Add(new DoubleArrayConverter());
+ arrays.Converters.Add(new Int32ArrayConverter());
+ var bridged = new JsonSerializerOptions(arrays);
+ bridged.Converters.Add(new RetainedDefinitionConverter(arrays));
+ return bridged;
+ }
+
+ private static void WriteBinary(Utf8JsonWriter writer, string type, long offset, int length)
+ {
+ writer.WriteStartObject();
+ writer.WriteString("$binary", type);
+ writer.WriteNumber("byteOffset", offset);
+ writer.WriteNumber("length", length);
+ writer.WriteEndObject();
+ }
+
+ private sealed class DoubleArrayConverter : JsonConverter<double[]>
+ {
+ public override double[]? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+ {
+ if (reader.TokenType == JsonTokenType.Null) return null;
+ var values = new List<double>();
+ while (reader.Read() && reader.TokenType != JsonTokenType.EndArray) values.Add(reader.GetDouble());
+ return values.ToArray();
+ }
+
+ public override void Write(Utf8JsonWriter writer, double[] value, JsonSerializerOptions options)
+ {
+ if (Current is { } bridge && value.Length >= BinaryThreshold)
+ {
+ WriteBinary(writer, "f64", bridge.Append(MemoryMarshal.AsBytes(value.AsSpan())), value.Length);
+ return;
+ }
+ writer.WriteStartArray();
+ foreach (var item in value) writer.WriteNumberValue(item);
+ writer.WriteEndArray();
+ }
+ }
+
+ private sealed class Int32ArrayConverter : JsonConverter<int[]>
+ {
+ public override int[]? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+ {
+ if (reader.TokenType == JsonTokenType.Null) return null;
+ var values = new List<int>();
+ while (reader.Read() && reader.TokenType != JsonTokenType.EndArray) values.Add(reader.GetInt32());
+ return values.ToArray();
+ }
+
+ public override void Write(Utf8JsonWriter writer, int[] value, JsonSerializerOptions options)
+ {
+ if (Current is { } bridge && value.Length >= BinaryThreshold)
+ {
+ WriteBinary(writer, "i32", bridge.Append(MemoryMarshal.AsBytes(value.AsSpan())), value.Length);
+ return;
+ }
+ writer.WriteStartArray();
+ foreach (var item in value) writer.WriteNumberValue(item);
+ writer.WriteEndArray();
+ }
+ }
+
+ private sealed class RetainedDefinitionConverter(JsonSerializerOptions definitionOptions) : JsonConverter<AssemblyDisplayMeshDefinition>
+ {
+ public override AssemblyDisplayMeshDefinition Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+ throw new NotSupportedException("Display mesh definitions are output only.");
+
+ public override void Write(Utf8JsonWriter writer, AssemblyDisplayMeshDefinition value, JsonSerializerOptions options)
+ {
+ if (Current?.Retained?.Contains(value) == true)
+ {
+ writer.WriteStartObject();
+ writer.WriteString("id", value.Id);
+ writer.WriteString("identity", value.Identity);
+ writer.WriteBoolean("retained", true);
+ writer.WriteEndObject();
+ return;
+ }
+ JsonSerializer.Serialize(writer, value, definitionOptions);
+ }
+ }
+}
diff --git a/Aetheris.Web.Runtime/sdk/src/index.js b/Aetheris.Web.Runtime/sdk/src/index.js
index 9773daf6..61a27204 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.js
+++ b/Aetheris.Web.Runtime/sdk/src/index.js
@@ -110,10 +110,25 @@ export class Aetheris {
get workerTiming() { return this.transport.lastTiming ?? null; }
}
+/** BUILD-PERF-M3: a rebuild references definitions this session already holds instead of
+ * resending them; substitute them by id. */
+function resolveRetained(snapshot, previous) {
+ const definitions = snapshot?.mesh?.definitions;
+ if (!definitions?.some(definition => definition.retained)) return;
+ const held = new Map((previous?.definitions ?? []).map(definition => [definition.id, definition]));
+ snapshot.mesh.definitions = definitions.map(definition => {
+ if (!definition.retained) return definition;
+ const kept = held.get(definition.id);
+ if (!kept) throw new AetherisError('retained-definition-missing', `Display definition '${definition.id}' was retained but is not held by this session.`);
+ return kept;
+ });
+}
+
export class ModelSession {
constructor(transport, snapshot) { this.transport = transport; this.apply(snapshot); this.queue = Promise.resolve(); }
get workerTiming() { return this.transport.lastTiming ?? null; }
apply(snapshot) {
+ resolveRetained(snapshot, this.mesh);
Object.assign(this, snapshot);
this._rangesBySemantic = new Map();
this._rangesBySource = new Map();
diff --git a/Aetheris.Web.Runtime/sdk/src/runtime.js b/Aetheris.Web.Runtime/sdk/src/runtime.js
index 77ec4761..0e6b2162 100644
--- a/Aetheris.Web.Runtime/sdk/src/runtime.js
+++ b/Aetheris.Web.Runtime/sdk/src/runtime.js
@@ -2,18 +2,43 @@ export function normalizeMesh(value) {
const mesh = value?.model?.mesh ?? value?.mesh;
if (!mesh?.definitions) return value;
for (const definition of mesh.definitions) {
+ // A retained definition is resolved by ModelSession from the one it already holds.
+ if (definition.retained) continue;
if (!(definition.positions instanceof Float64Array)) definition.positions = Float64Array.from(definition.positions);
if (!(definition.normals instanceof Float64Array)) definition.normals = Float64Array.from(definition.normals);
- if (!(definition.indices instanceof Uint32Array)) definition.indices = Uint32Array.from(definition.indices);
+ // Bridge indices arrive as Int32Array views; indices are non-negative, so reinterpret in place.
+ if (definition.indices instanceof Int32Array) definition.indices = new Uint32Array(definition.indices.buffer, definition.indices.byteOffset, definition.indices.length);
+ else if (!(definition.indices instanceof Uint32Array)) definition.indices = Uint32Array.from(definition.indices);
}
return value;
}
+/** Distinct ArrayBuffers behind the mesh arrays (bridge arrays share one buffer). */
export function transferables(value) {
- const result = [];
+ const result = new Set();
const mesh = value?.model?.mesh ?? value?.mesh;
- for (const definition of mesh?.definitions ?? []) result.push(definition.positions.buffer, definition.normals.buffer, definition.indices.buffer);
- return result;
+ for (const definition of mesh?.definitions ?? []) {
+ if (definition.retained) continue;
+ for (const array of [definition.positions, definition.normals, definition.indices]) if (array?.buffer) result.add(array.buffer);
+ }
+ return [...result];
+}
+
+/** BUILD-PERF-M3: replace {"$binary","byteOffset","length"} placeholders by typed-array views. */
+export function reviveBinary(value, bytes) {
+ if (Array.isArray(value)) {
+ for (let i = 0; i < value.length; i++) { const item = value[i]; if (item !== null && typeof item === 'object') value[i] = reviveBinary(item, bytes); }
+ return value;
+ }
+ const type = value.$binary;
+ if (type !== undefined) {
+ const start = bytes.byteOffset + value.byteOffset;
+ if (type === 'f64') return new Float64Array(bytes.buffer, start, value.length);
+ if (type === 'i32') return new Int32Array(bytes.buffer, start, value.length);
+ throw new Error(`Unknown binary array type '${type}'.`);
+ }
+ for (const key in value) { const item = value[key]; if (item !== null && typeof item === 'object') value[key] = reviveBinary(item, bytes); }
+ return value;
}
export async function createRuntime(runtimeBase = new URL('./runtime/', import.meta.url)) {
@@ -28,9 +53,12 @@ export async function createRuntime(runtimeBase = new URL('./runtime/', import.m
const exports = await runtime.getAssemblyExports('Aetheris.Web.Runtime.dll');
const assemblyExportsMilliseconds = performance.now() - exportsStart;
const invoke = exports.Aetheris.Web.Runtime.Program.Invoke;
+ // A runtime with TakeBinary speaks bridge 1: binary mesh arrays and retained definitions.
+ const takeBinary = exports.Aetheris.Web.Runtime.Program.TakeBinary;
+ const bridge = typeof takeBinary === 'function' ? 1 : undefined;
const requestRuntime = request => {
const start = performance.now();
- const requestJson = JSON.stringify(request);
+ const requestJson = JSON.stringify(bridge ? { ...request, bridge } : request);
const requestMilliseconds = performance.now() - start;
const invokeStart = performance.now();
const responseJson = invoke(requestJson);
@@ -38,6 +66,18 @@ export async function createRuntime(runtimeBase = new URL('./runtime/', import.m
const parseStart = performance.now();
const envelope = JSON.parse(responseJson);
const responseParseMilliseconds = performance.now() - parseStart;
+ const binaryStart = performance.now();
+ let binaryBytes = 0;
+ if (bridge) {
+ let bytes = takeBinary();
+ if (bytes?.byteLength) {
+ // Float64Array views need 8-byte alignment of the underlying buffer offset.
+ if (!(bytes instanceof Uint8Array) || bytes.byteOffset % 8 !== 0) bytes = Uint8Array.from(bytes);
+ binaryBytes = bytes.byteLength;
+ if (envelope.ok) reviveBinary(envelope.result, bytes);
+ }
+ }
+ const binaryMilliseconds = performance.now() - binaryStart;
if (!envelope.ok) {
const error = new Error(envelope.error.message);
error.name = 'AetherisError'; error.code = envelope.error.code; error.details = envelope.error.details;
@@ -47,8 +87,8 @@ export async function createRuntime(runtimeBase = new URL('./runtime/', import.m
const result = normalizeMesh(envelope.result);
const meshNormalizeMilliseconds = performance.now() - normalizeStart;
if (request.performance && result?.model?.timings) result.model.timings.bridge = {
- requestMilliseconds, invokeMilliseconds, responseParseMilliseconds,
- meshNormalizeMilliseconds, responseBytes: responseJson.length
+ requestMilliseconds, invokeMilliseconds, responseParseMilliseconds, binaryMilliseconds,
+ meshNormalizeMilliseconds, responseBytes: responseJson.length, binaryBytes, bridge: bridge ?? 0
};
return result;
};
diff --git a/Aetheris.Web.Runtime/sdk/tests/bridge.test.mjs b/Aetheris.Web.Runtime/sdk/tests/bridge.test.mjs
new file mode 100644
index 00000000..d61b681d
--- /dev/null
+++ b/Aetheris.Web.Runtime/sdk/tests/bridge.test.mjs
@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ModelSession } from '../src/index.js';
+import { normalizeMesh, reviveBinary, transferables } from '../src/runtime.js';
+
+function binary(positions, indices) {
+ const bytes = new Uint8Array(positions.length * 8 + indices.length * 4);
+ new Float64Array(bytes.buffer, 0, positions.length).set(positions);
+ new Int32Array(bytes.buffer, positions.length * 8, indices.length).set(indices);
+ return bytes;
+}
+
+function definition(id, positionsAt, indicesAt) {
+ return { id, identity: id, ranges: [], positions: { $binary: 'f64', byteOffset: positionsAt, length: 3 },
+ normals: { $binary: 'f64', byteOffset: positionsAt, length: 3 }, indices: { $binary: 'i32', byteOffset: indicesAt, length: 3 } };
+}
+
+test('binary placeholders become exact typed-array views of one buffer', () => {
+ const bytes = binary([0.1, -2.5, 1e-300], [0, 1, 2]);
+ const result = reviveBinary({ model: { mesh: { definitions: [definition('a', 0, 24)], occurrences: [] } } }, bytes);
+ const [revived] = normalizeMesh(result).model.mesh.definitions;
+ assert.deepEqual([...revived.positions], [0.1, -2.5, 1e-300]);
+ assert.ok(revived.indices instanceof Uint32Array);
+ assert.deepEqual([...revived.indices], [0, 1, 2]);
+ assert.equal(revived.positions.buffer, bytes.buffer);
+ assert.equal(revived.indices.buffer, bytes.buffer, 'indices are reinterpreted, not copied');
+});
+
+test('transferables lists each shared buffer once and skips retained definitions', () => {
+ const bytes = binary([1, 2, 3], [0, 1, 2]);
+ const result = normalizeMesh(reviveBinary({ model: { mesh: { definitions: [definition('a', 0, 24), definition('b', 0, 24),
+ { id: 'c', identity: 'c', retained: true }] } } }, bytes));
+ assert.deepEqual(transferables(result), [bytes.buffer]);
+});
+
+test('a rebuild substitutes retained definitions with the ones the session holds', () => {
+ const held = { id: 'kept', identity: 'kept', positions: new Float64Array([1, 2, 3]), normals: new Float64Array(3), indices: new Uint32Array([0, 1, 2]), ranges: [] };
+ const fresh = { id: 'new', identity: 'new', positions: new Float64Array(3), normals: new Float64Array(3), indices: new Uint32Array([0, 1, 2]), ranges: [] };
+ const session = new ModelSession({}, { revision: 1, mesh: { definitions: [held], occurrences: [] } });
+ session.apply({ revision: 2, mesh: { definitions: [{ id: 'kept', identity: 'kept', retained: true }, fresh], occurrences: [] } });
+ assert.equal(session.revision, 2);
+ assert.equal(session.mesh.definitions[0], held);
+ assert.equal(session.mesh.definitions[1], fresh);
+});
+
+test('a retained definition the session does not hold is an error, not a silent hole', () => {
+ const session = new ModelSession({}, { revision: 1, mesh: { definitions: [], occurrences: [] } });
+ assert.throws(() => session.apply({ revision: 2, mesh: { definitions: [{ id: 'missing', identity: 'missing', retained: true }], occurrences: [] } }),
+ error => error.code === 'retained-definition-missing');
+});
diff --git a/docs/development/milestones/general/build-perf-ladder.md b/docs/development/milestones/general/build-perf-ladder.md
index 3b842d05..f5b5bda3 100644
--- a/docs/development/milestones/general/build-perf-ladder.md
+++ b/docs/development/milestones/general/build-perf-ladder.md
@@ -121,6 +121,12 @@ Diagnostics, source maps and STEP match a clean build exactly.
Exit: guitar JSON response < 1 MB; mesh content hash identical; browser time between "build done
in C#" and "mesh on GPU" measured and reported.
+**Result** ([BUILD-PERF-M3](../../../release/BUILD-PERF-M3.md)): success. Duplicate top-level mesh
+removed (responses halved), binary arrays (`bridge: 1`, `TakeBinary`) and retained definitions.
+Guitar cold response 942 KB JSON + 4.8 MB binary; a root-comment edit 165 KB with 56/56 definitions
+retained; every bridged model proven identical to the legacy model (`verify-bridge`). Browser dev
+runtime: ATLAS root-comment edit 5.66 → 1.53 s, with 0.07 s outside the kernel. Next: M2.
+
### M4 — Kernel hotspots
In order of measured share, re-profiled after M1–M3:
diff --git a/docs/release/BUILD-PERF-M3.md b/docs/release/BUILD-PERF-M3.md
new file mode 100644
index 00000000..c9c7f2e8
--- /dev/null
+++ b/docs/release/BUILD-PERF-M3.md
@@ -0,0 +1,70 @@
+# BUILD-PERF-M3 — Binary bridge
+
+Ladder: [build-perf-ladder.md](../development/milestones/general/build-perf-ladder.md) ·
+previous: [BUILD-PERF-M1](BUILD-PERF-M1.md). M3 ran before M2 because the M1 browser lane showed
+the response, not the kernel, dominating the edit floor (ATLAS: 4.1 of 5.7 s).
+
+**State: success.** In the browser, the response overhead of an edit fell from seconds to tens of
+milliseconds, and every bridged model is proven identical to the legacy JSON model.
+
+## Changes
+
+1. **The duplicate mesh is gone.** Every build response carried `mesh`, `tree` and `entityIds`
+ twice: inside `model` (the snapshot the SDK applies) and again at the top level, which nothing
+ reads. Responses now carry them once (legacy and bridged).
+2. **Binary arrays** (request `bridge: 1`, sent by the SDK when the runtime exports `TakeBinary`).
+ `double[]` and `int[]` of at least 64 elements are written to one little-endian, 8-byte-aligned
+ buffer and replaced in the JSON by `{"$binary":"f64"|"i32","byteOffset","length"}`. The runtime
+ (`WebResponseBridge`) applies this to every response shape (parts, assemblies, scenes).
+ `TakeBinary()` returns the buffer; the SDK revives typed-array views of it (`reviveBinary`),
+ reinterprets `i32` indices as the `Uint32Array` the contract promises (no copy), and transfers
+ the single buffer from the Worker. Values are bit-identical to the JSON path.
+3. **Retained definitions.** A rebuild writes a mesh definition the session's previous response
+ already delivered as `{"id","identity","retained":true}`. "Already delivered" is reference
+ identity: M1's display cache returns the same prepared definition object exactly when its
+ input key is unchanged. `ModelSession.apply` substitutes the definition it holds and fails
+ with `retained-definition-missing` rather than leave a hole. The stored snapshot keeps full
+ definitions, so the `snapshot` operation is unaffected. telos already reuses GPU geometry for
+ the same arrays, so retained definitions are not re-uploaded either.
+4. **Verification tooling.** `Aetheris.Web.Perf verify-bridge <project> <root>` builds the project
+ in a legacy session and a bridged session through cold build, no-change rebuild and root-comment
+ edit, reconstructs each bridged model as the SDK does and requires it to equal the legacy model.
+ SDK tests (`tests/bridge.test.mjs`): exact revival into one buffer, index reinterpretation,
+ deduplicated transferables, retained substitution and the missing-definition error.
+ The browser lane records the runtime's bridge timings.
+
+Compatibility: an older SDK does not send `bridge` and receives legacy JSON (minus the duplicate
+top-level fields, which the SDK never read). The native perf harness uses legacy mode, so the
+M0/M1 hash budgets remain valid.
+
+## Results
+
+### Response size (native, `verify-bridge`; all steps identical to legacy)
+
+| Project | Before M3 | Legacy now | Bridged cold | Bridged edit (root comment) |
+|---|---|---|---|---|
+| guitar | 17.2 MB | 8.6 MB | 942 KB JSON + 4.8 MB binary | **165 KB**, 56/56 definitions retained |
+| atlas | 3.3 MB | 1.7 MB | 323 KB + 910 KB | **118 KB**, 24/24 retained |
+| house (Scene) | 5.0 MB | 2.5 MB | 663 KB + 1.6 MB | 647 KB + 1.6 MB (Scenes do not reuse definitions yet) |
+| bolt (part) | 13.3 MB | 6.6 MB | 1.6 MB + 2.8 MB | 1.6 MB + 2.8 MB (one definition, rebuilt) |
+
+### Browser (interpreted dev runtime, headless Chromium, same container)
+
+| Project | Scenario | M1 | M3 | of which outside the kernel |
+|---|---|---|---|---|
+| atlas | root comment edit | 5.66 s | **1.53 s** | 4.1 s → **0.07 s** |
+| atlas | no-change rebuild | 5.78 s | **1.65 s** | |
+| house | root comment edit | 19.4 s | **13.1 s** | 7.0 s → 0.8 s |
+| atlas / house | cold | 328 s / 74 s | 327 s / 65 s | response parse 1–2 ms, binary revive 3–6 ms |
+
+Browser STEP for ATLAS is unchanged since M0 (`f6c57e57…`).
+
+### What remains
+
+- **Edit floor is now kernel time:** ATLAS 1.46 s, house 12.3 s (scene compile) on the dev
+ runtime → M2.
+- **Edge polylines stay JSON** (thousands of `[x,y,z]` triples; bolt 1.4 MB). A flattened binary
+ edge layout needs a contract change; deferred until it shows up in a profile.
+- **Parts and Scenes are not retained:** a single part is one definition; Scenes do not use the
+ assembly display cache → M2.
+- **AOT browser numbers** still need a machine with > 8 GB RAM to link.