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.csprojindex 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.csindex 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.csnew file mode 100644index 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.jsonindex 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.csindex 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 Programstring? 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 Programpublic 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 Programtree = 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.csnew file mode 100644index 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.jsindex 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.jsindex 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.mconst 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.mconst 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.mconst 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.mjsnew file mode 100644index 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.mdindex 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 donein 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 hotspotsIn order of measured share, re-profiled after M1–M3:diff --git a/docs/release/BUILD-PERF-M3.md b/docs/release/BUILD-PERF-M3.mdnew file mode 100644index 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.