Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Make V8 geometry qualification portable across platforms

Yuechen Lifbe48b0c50ad
diff --git a/demos/Aetheris.EditableV8.Tests/EngineTests.cs b/demos/Aetheris.EditableV8.Tests/EngineTests.cs
index 983c7742..8bc15e36 100644
--- a/demos/Aetheris.EditableV8.Tests/EngineTests.cs
+++ b/demos/Aetheris.EditableV8.Tests/EngineTests.cs
@@ -1,3 +1,5 @@
+using System.IO.Compression;
+using System.Security.Cryptography;
using System.Text.Json;
using Aetheris.EditableV8;
using Aetheris.Kernel.Firmament.Assembly;
@@ -79,30 +81,60 @@ public sealed class EngineTests
Assert.NotNull(directory);
using var reference = JsonDocument.Parse(File.ReadAllText(Path.Combine(directory!.FullName,
"fixtures/Canonical/EditableV8/geometry-reference.expected.json")));
- var definitions = mesh.Definitions.ToDictionary(d => d.Id, d => Fingerprint(d), StringComparer.Ordinal);
+ using var meshes = ZipFile.OpenRead(Path.Combine(directory.FullName,
+ "fixtures/Canonical/EditableV8/geometry-reference.meshes.zip"));
+ var definitions = mesh.Definitions.ToDictionary(d => d.Id, StringComparer.Ordinal);
var occurrences = mesh.Occurrences.ToDictionary(o => o.Id, StringComparer.Ordinal);
var bindings = motion.Bindings.ToDictionary(b => b.Name, StringComparer.Ordinal);
Assert.Equal(reference.RootElement.GetProperty("bodyCount").GetInt32(), bindings.Count);
+ Assert.Equal(reference.RootElement.GetProperty("definitionCount").GetInt32(), definitions.Count);
+ var compared = new HashSet<(string DefinitionId, string Hash)>();
foreach (var row in reference.RootElement.GetProperty("bindings").EnumerateArray()) {
var binding = bindings[row.GetProperty("name").GetString()!];
- Assert.True(row.GetProperty("meshSha256").GetString() == definitions[occurrences[binding.OccurrenceId!].DefinitionId!], "Part geometry changed for " + binding.Name);
+ var definition = definitions[occurrences[binding.OccurrenceId!].DefinitionId!];
+ var hash = row.GetProperty("meshSha256").GetString()!;
+ if (compared.Add((definition.Id, hash)))
+ {
+ var entry = meshes.GetEntry(hash + ".bin");
+ Assert.NotNull(entry);
+ using var data = new MemoryStream();
+ using (var stream = entry.Open()) stream.CopyTo(data);
+ // Keep the original reference bytes; only the live comparison is tolerant.
+ Assert.Equal(hash, Convert.ToHexString(SHA256.HashData(data.ToArray())));
+ data.Position = 0;
+ using var reader = new BinaryReader(data);
+ foreach (var (values, channel) in new[] { (definition.Positions, "positions"), (definition.Normals, "normals") })
+ {
+ Assert.Equal(reader.ReadInt32(), values.Length);
+ for (var i = 0; i < values.Length; i++)
+ {
+ var expected = reader.ReadDouble();
+ Assert.True(ComponentMatches(expected, values[i]),
+ $"Part geometry changed for {binding.Name}: {channel}[{i}] expected {expected:R}, actual {values[i]:R}");
+ }
+ }
+ Assert.Equal(reader.ReadInt32(), definition.Indices.Length);
+ foreach (var index in definition.Indices) Assert.Equal(reader.ReadInt32(), index);
+ Assert.Equal(data.Length, data.Position);
+ }
var oldRest = row.GetProperty("rest").EnumerateArray().Select(v => v.GetDouble());
Assert.True(binding.Rest.Zip(oldRest).All(p => double.Abs(p.First - p.Second) <= 1e-9), "Rest geometry changed for " + binding.Name);
}
}
- private static string Fingerprint(AssemblyDisplayMeshDefinition definition)
+ // libm and numerically differentiated spring normals vary across platforms.
+ // Positions are in mm; normals are unitless. Topology remains exact above.
+ private static bool ComponentMatches(double expected, double actual) =>
+ double.IsFinite(expected) && double.IsFinite(actual) && double.Abs(expected - actual) <= 1e-9;
+
+ [Theory]
+ [InlineData(20d, 20.0000000001d, true)]
+ [InlineData(20d, 20.00001d, false)]
+ [InlineData(0d, double.NaN, false)]
+ [InlineData(0d, double.PositiveInfinity, false)]
+ public void GeometryComparisonAdmitsRoundoffButRejectsChanges(double expected, double actual, bool matches)
{
- using var data = new MemoryStream();
- using (var writer = new BinaryWriter(data, System.Text.Encoding.UTF8, leaveOpen: true)) {
- foreach (var values in new[] { definition.Positions, definition.Normals }) {
- writer.Write(values.Length);
- foreach (var value in values) writer.Write(value == 0 ? 0d : value);
- }
- writer.Write(definition.Indices.Length);
- foreach (var index in definition.Indices) writer.Write(index);
- }
- return Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(data.ToArray()));
+ Assert.Equal(matches, ComponentMatches(expected, actual));
}
}
diff --git a/docs/release/FIRMAMENT-ASSEMBLY-REUSE.md b/docs/release/FIRMAMENT-ASSEMBLY-REUSE.md
index d4a8596e..a6bdd742 100644
--- a/docs/release/FIRMAMENT-ASSEMBLY-REUSE.md
+++ b/docs/release/FIRMAMENT-ASSEMBLY-REUSE.md
@@ -161,10 +161,13 @@ parity and source hashes. Intermediate failing runs are not final acceptance.
The durable `geometry-reference.expected.json` fixture captures the original
baseline at the implementation-base commit: 171 logical Part bindings, local
-mesh fingerprints and solved world matrices. Its test hashes little-endian array
-lengths and position/normal/index data, normalizing signed zero; world matrices
-have a 1e-9 tolerance. The JSON records the original generated-source hash and
-reproduction provenance. Raw old meshes and per-run outputs stay ignored.
+mesh fingerprints and solved world matrices. The adjacent compressed numeric
+golden now permits cross-platform comparisons: its bytes must match those original
+fingerprints, while live positions/normals use a 1e-9 component tolerance and
+indices remain exact. World matrices retain a 1e-9 tolerance. See the
+[fixture contract](../../fixtures/Canonical/EditableV8/README.md) for format,
+Windows/Linux measurements and recovery instructions. The JSON retains the original
+generated-source hash and provenance. Per-run mesh exports stay ignored.
Reproduce the build/test lanes from the repository root:
diff --git a/fixtures/Canonical/EditableV8/README.md b/fixtures/Canonical/EditableV8/README.md
new file mode 100644
index 00000000..abf277f2
--- /dev/null
+++ b/fixtures/Canonical/EditableV8/README.md
@@ -0,0 +1,34 @@
+# Editable V8 geometry reference
+
+`geometry-reference.expected.json` retains the original implementation's 171
+binding names, 21 mesh fingerprints and solved world matrices. Its source hash
+and implementation commit identify the pre-refactor baseline.
+
+`geometry-reference.meshes.zip` recovers the numeric data behind those existing
+fingerprints. Each entry is named `<original SHA-256>.bin` and contains
+little-endian position and normal arrays (Int32 length, then Float64 elements),
+followed by indices (Int32 length and elements). Signed zero is normalized.
+The test verifies each entry against the unchanged original fingerprint.
+
+The numeric golden is necessary because a byte hash cannot distinguish geometry
+changes from platform math roundoff. Windows/Linux comparison on 2026-10-16 found
+identical array lengths and indices, maximum position delta `1.013e-13 mm`, and
+maximum normal-component delta `2.267e-10` (spring normals). The live test allows
+`1e-9 mm` per position component and `1e-9` per normal component, requires finite
+values, and compares indices exactly. World matrices retain their `1e-9` bound.
+No production geometry or original fingerprint was changed.
+
+To recover the archive, run the demo at the original implementation commit with
+default `V8Spec` (see the JSON's `reproduction` field), then from the current
+repository root:
+
+```powershell
+python scripts/freeze-editable-v8-reference.py path/to/baseline.mesh.json
+```
+
+The command writes under ignored `artifacts/local/v8-ci/`. It refuses any input
+whose meshes do not exactly match all original fingerprints; it cannot rebaseline
+changed geometry. The checked-in archive was recovered from the Windows baseline
+with all 21 original hashes verified. It is a compressed durable regression golden,
+not a per-run mesh export. Its full numeric arrays permit tolerance comparisons
+without the boundary failures introduced by rounding and hashing floats.
diff --git a/fixtures/Canonical/EditableV8/geometry-reference.meshes.zip b/fixtures/Canonical/EditableV8/geometry-reference.meshes.zip
new file mode 100644
index 00000000..82029bb5
Binary files /dev/null and b/fixtures/Canonical/EditableV8/geometry-reference.meshes.zip differ
diff --git a/scripts/freeze-editable-v8-reference.py b/scripts/freeze-editable-v8-reference.py
new file mode 100644
index 00000000..7cc8e907
--- /dev/null
+++ b/scripts/freeze-editable-v8-reference.py
@@ -0,0 +1,45 @@
+"""Recover the V8 numeric golden only from meshes matching the existing hashes."""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import zipfile
+
+
+def freeze(source: Path, output: Path) -> None:
+ root = Path(__file__).resolve().parent.parent
+ reference = json.loads((root / "fixtures/Canonical/EditableV8/geometry-reference.expected.json").read_text())
+ expected = {row["meshSha256"] for row in reference["bindings"]}
+ entries = {}
+ for definition in json.loads(source.read_text())["definitions"]:
+ data = bytearray()
+ for channel in ("positions", "normals"):
+ values = definition[channel]
+ data.extend(struct.pack("<i", len(values)))
+ for value in values:
+ data.extend(struct.pack("<d", value if value else 0))
+ indices = definition["indices"]
+ data.extend(struct.pack("<i", len(indices)))
+ data.extend(struct.pack(f"<{len(indices)}i", *indices))
+ fingerprint = hashlib.sha256(data).hexdigest().upper()
+ if fingerprint not in expected:
+ raise ValueError(f"Mesh does not match the original baseline: {fingerprint}")
+ entries[fingerprint] = data
+ if set(entries) != expected:
+ raise ValueError("Missing original baseline definitions")
+ output.parent.mkdir(parents=True, exist_ok=True)
+ with zipfile.ZipFile(output, "w") as archive:
+ for fingerprint, data in sorted(entries.items()):
+ entry = zipfile.ZipInfo(fingerprint + ".bin", date_time=(2026, 10, 16, 0, 0, 0))
+ entry.compress_type = zipfile.ZIP_DEFLATED
+ archive.writestr(entry, data, compresslevel=9)
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("mesh", type=Path)
+ parser.add_argument("--output", type=Path, default=Path("artifacts/local/v8-ci/geometry-reference.meshes.zip"))
+ args = parser.parse_args()
+ freeze(args.mesh, args.output)