Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

holes.

Yuechen Li1948100b00de
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
index 1fcaa479..c9a7184a 100644
--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
@@ -24,7 +24,8 @@ public static class BrepBooleanBoxCylinderHoleBuilder
return BuildComposition(updatedComposition, tolerance);
}
- public static KernelResult<BrepBody> BuildComposition(SafeBooleanComposition composition, ToleranceContext tolerance)
+ public static KernelResult<BrepBody> BuildComposition(SafeBooleanComposition composition, ToleranceContext tolerance,
+ Action<string, FaceId>? onConstructedHoleWall = null)
{
ArgumentNullException.ThrowIfNull(composition);
_ = tolerance;
@@ -127,7 +128,7 @@ public static class BrepBooleanBoxCylinderHoleBuilder
}
}
- return CreateComposedThroughHoleBody(composition, tolerance);
+ return CreateComposedThroughHoleBody(composition, tolerance, onConstructedHoleWall);
}
/// <summary>
@@ -719,7 +720,8 @@ public static class BrepBooleanBoxCylinderHoleBuilder
: KernelResult<BrepBody>.Failure(validation.Diagnostics);
}
- private static KernelResult<BrepBody> CreateComposedThroughHoleBody(SafeBooleanComposition composition, ToleranceContext tolerance)
+ private static KernelResult<BrepBody> CreateComposedThroughHoleBody(SafeBooleanComposition composition, ToleranceContext tolerance,
+ Action<string, FaceId>? onConstructedHoleWall = null)
{
var box = composition.OuterBox;
var holes = composition.Holes;
@@ -812,9 +814,11 @@ public static class BrepBooleanBoxCylinderHoleBuilder
// the bottom circle, back up the reversed seam, then the top
// circle. The previous top/bottom ordering was incidence-manifold
// but disconnected in declared coedge traversal.
- holeFaces.Add(AddKnownFace(builder, [
+ var wallFace = AddKnownFace(builder, [
AddSurgeryLoop(builder, [Forward(hole.Seam), Forward(hole.BottomCircle), Reversed(hole.Seam), Reversed(hole.TopCircle)])
- ]));
+ ]);
+ holeFaces.Add(wallFace);
+ if (hole.Hole.FeatureId is { } featureId) onConstructedHoleWall?.Invoke(featureId, wallFace);
}
var blindBottomFaces = new List<FaceId>();
diff --git a/Aetheris.Kernel.Core/Brep/BrepPrimitives.cs b/Aetheris.Kernel.Core/Brep/BrepPrimitives.cs
index 5f09c2ec..675ea860 100644
--- a/Aetheris.Kernel.Core/Brep/BrepPrimitives.cs
+++ b/Aetheris.Kernel.Core/Brep/BrepPrimitives.cs
@@ -138,7 +138,12 @@ public static class BrepPrimitives
}
public static KernelResult<BrepBody> CreateBox(double width, double height, double depth)
+ => CreateBoxWithTopology(width, height, depth, out _);
+
+ public static KernelResult<BrepBody> CreateBoxWithTopology(double width, double height, double depth,
+ out BrepExtrudeConstructionTopology? constructionTopology)
{
+ constructionTopology = null;
var diagnostics = ValidatePositiveFinite((width, nameof(width)), (height, nameof(height)), (depth, nameof(depth)));
if (diagnostics.Count > 0)
{
@@ -161,7 +166,7 @@ public static class BrepPrimitives
Direction3D.Create(new Vector3D(0d, 0d, 1d)),
Direction3D.Create(new Vector3D(1d, 0d, 0d)));
- return BrepExtrude.Create(profile.Value, frame, depth);
+ return BrepExtrude.CreateWithTopology(profile.Value, frame, depth, out constructionTopology);
}
public static KernelResult<BrepBody> CreateCylinder(double radius, double height)
diff --git a/Aetheris.Kernel.Core/Brep/Features/BrepExtrude.cs b/Aetheris.Kernel.Core/Brep/Features/BrepExtrude.cs
index a760f5d6..e783f1df 100644
--- a/Aetheris.Kernel.Core/Brep/Features/BrepExtrude.cs
+++ b/Aetheris.Kernel.Core/Brep/Features/BrepExtrude.cs
@@ -8,13 +8,23 @@ using Aetheris.Kernel.Core.Topology;
namespace Aetheris.Kernel.Core.Brep.Features;
+/// <summary>Topology IDs captured at construction, before export or tessellation.</summary>
+public sealed record BrepExtrudeConstructionTopology(FaceId BottomFace, FaceId TopFace,
+ IReadOnlyList<FaceId> SideFaces, IReadOnlyList<EdgeId> BottomEdges,
+ IReadOnlyList<EdgeId> TopEdges, IReadOnlyList<EdgeId> VerticalEdges);
+
/// <summary>
/// M10 minimal programmatic extrusion for a single outer polyline profile.
/// </summary>
public static class BrepExtrude
{
public static KernelResult<BrepBody> Create(PolylineProfile2D profile, ExtrudeFrame3D frame, double depth)
+ => CreateWithTopology(profile, frame, depth, out _);
+
+ public static KernelResult<BrepBody> CreateWithTopology(PolylineProfile2D profile, ExtrudeFrame3D frame, double depth,
+ out BrepExtrudeConstructionTopology? constructionTopology)
{
+ constructionTopology = null;
var diagnostics = new List<KernelDiagnostic>();
if (!double.IsFinite(depth) || depth <= 0d)
{
@@ -139,6 +149,8 @@ public static class BrepExtrude
var body = new BrepBody(builder.Model, geometry, bindings);
var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);
+ if (validation.IsSuccess)
+ constructionTopology = new(faces[0], faces[1], faces.Skip(2).ToArray(), bottomEdges, topEdges, sideEdges);
return validation.IsSuccess
? KernelResult<BrepBody>.Success(body, validation.Diagnostics)
: KernelResult<BrepBody>.Failure(validation.Diagnostics);
diff --git a/Aetheris.Kernel.Firmament.Tests/BoxRuntimeCorrespondenceTests.cs b/Aetheris.Kernel.Firmament.Tests/BoxRuntimeCorrespondenceTests.cs
new file mode 100644
index 00000000..3f5ebf07
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/BoxRuntimeCorrespondenceTests.cs
@@ -0,0 +1,101 @@
+using Aetheris.Kernel.Firmament.FirmamentV2;
+using Aetheris.Kernel.Firmament.Materializer;
+using Aetheris.Kernel.Core.Step242;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class BoxRuntimeCorrespondenceTests
+{
+ private const string Source = "Model BoxWitness { Units: mm Box Body { Size: [30mm, 20mm, 10mm] } }";
+
+ [Fact]
+ public void BoxFacesRetainConstructionIdentityForDirectDisplay()
+ {
+ var build = FirmamentBuildAndExport.CompileSource(Source);
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(item => item.Message)));
+ var body = Assert.IsType<Aetheris.Kernel.Core.Brep.BrepBody>(build.Value.RuntimeBody);
+ var correspondence = Assert.IsType<SemanticTopologyCorrespondence>(build.Value.RuntimeCorrespondence);
+ Assert.Equal("Body", correspondence.BodyStableId);
+ var sourceMap = new GeometrySourceMap(correspondence);
+ Assert.True(sourceMap.TryGetSourceSpan("Body", out var boxSpan));
+ Assert.Contains("Box Body", Source.Substring(boxSpan.Start, boxSpan.Length));
+ var faces = correspondence.Descendants.Where(item => item.Kind == "Face").ToArray();
+ Assert.Equal(6, faces.Length);
+ Assert.Equal(6, faces.Select(item => item.Face).Distinct().Count());
+ Assert.All(faces, item =>
+ {
+ Assert.Equal(SemanticTopologyAddressability.DerivedStable, item.Addressability);
+ Assert.Contains(body.Topology.Faces, face => face.Id == item.Face);
+ });
+ Assert.Equal("Body.face(+Z)", Assert.Single(faces, item => item.FirmamentSelector == "face(+Z)").StableId);
+ var top = Assert.Single(faces, item => item.FirmamentSelector == "face(+Z)");
+ Assert.True(sourceMap.TryGetByBrepFace(top.Face!.Value, out var mappedTop));
+ Assert.Equal(top, mappedTop);
+ Assert.Contains(top, sourceMap.GetEntitiesForSemanticKey(top.StableId));
+ Assert.Equal(6, sourceMap.GetEntitiesForSourceSymbol("Body").Count(item => item.Face.HasValue));
+ Assert.Equal("Body.face(+X)", Assert.Single(faces, item => item.FirmamentSelector == "face(+X)").StableId);
+ foreach (var face in faces)
+ {
+ var binding = Assert.Single(body.Bindings.FaceBindings, item => item.FaceId == face.Face);
+ var normal = body.Geometry.GetSurface(binding.SurfaceGeometryId).Plane!.Value.Normal;
+ var axis = face.FirmamentSelector![6];
+ var expected = face.FirmamentSelector[5] == '+' ? 1d : -1d;
+ var component = axis switch { 'X' => normal.X, 'Y' => normal.Y, 'Z' => normal.Z, _ => throw new InvalidOperationException() };
+ Assert.Equal(expected, component, 10);
+ }
+ Assert.Contains(correspondence.Descendants, item => item.Kind == "Edge" && item.Edge.HasValue && item.FirmamentSelector is null);
+ }
+
+ [Fact]
+ public void BoxSizeEditPreservesSemanticFaceIdentityButBodyRenameInvalidatesIt()
+ {
+ var initial = FirmamentBuildAndExport.CompileSource(Source).Value.RuntimeCorrespondence!;
+ var resized = FirmamentBuildAndExport.CompileSource(Source.Replace("10mm]", "40mm]", StringComparison.Ordinal)).Value.RuntimeCorrespondence!;
+ var renamed = FirmamentBuildAndExport.CompileSource(Source.Replace("Box Body", "Box Renamed", StringComparison.Ordinal)).Value.RuntimeCorrespondence!;
+ Assert.Equal(initial.Descendants.Where(item => item.Face.HasValue).Select(item => item.StableId),
+ resized.Descendants.Where(item => item.Face.HasValue).Select(item => item.StableId));
+ Assert.DoesNotContain(renamed.Descendants, item => item.StableId == "Body.face(+Z)");
+ }
+
+ [Fact]
+ public void FormattedTopFaceIsAcceptedByExistingFirmamentPmiBinder()
+ {
+ var source = Source.Replace(" } }", " } Pmi { Datum A { Target: face(+Z) } } }", StringComparison.Ordinal);
+ var parsed = FirmamentV2Parser.Parse(source);
+ Assert.True(parsed.IsSuccess, string.Join("; ", parsed.Diagnostics));
+ Assert.Contains(parsed.Document!.Pmi!, datum => datum.Target == "face(+Z)");
+ var build = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(item => item.Message)));
+ Assert.NotNull(build.Value.RuntimeCorrespondence);
+ }
+
+ [Fact]
+ public void DirectDisplayDoesNotChangeStepExportOrReimport()
+ {
+ var build = FirmamentBuildAndExport.CompileSource(Source);
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(item => item.Message)));
+ var reimport = Step242Importer.ImportBody(build.Value.StepText);
+ Assert.True(reimport.IsSuccess, string.Join("; ", reimport.Diagnostics.Select(item => item.Message)));
+ Assert.Equal(6, reimport.Value!.Topology.Faces.Count());
+ }
+
+ [Fact]
+ public void SourceMapAllowsSplitRoleButRejectsDuplicateBrepEntity()
+ {
+ var correspondence = FirmamentBuildAndExport.CompileSource(Source).Value.RuntimeCorrespondence!;
+ var faces = correspondence.Descendants.Where(item => item.Face.HasValue).ToArray();
+ var split = correspondence with { Descendants = correspondence.Descendants.Select(item =>
+ item == faces[1] ? item with { StableId = faces[0].StableId } : item).ToArray() };
+ var map = new GeometrySourceMap(split);
+ Assert.Equal(2, map.GetEntitiesForSemanticKey(faces[0].StableId).Count);
+ Assert.Throws<InvalidOperationException>(() => new GeometrySourceMap(correspondence with
+ {
+ Descendants = [.. correspondence.Descendants, faces[0]]
+ }));
+ Assert.Throws<InvalidOperationException>(() => new GeometrySourceMap(correspondence with
+ {
+ Descendants = correspondence.Descendants.Select(item => item == faces[1]
+ ? item with { StableId = faces[0].StableId, SourceStableId = "another-origin" } : item).ToArray()
+ }));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/HoleRuntimeCorrespondenceTests.cs b/Aetheris.Kernel.Firmament.Tests/HoleRuntimeCorrespondenceTests.cs
new file mode 100644
index 00000000..03e2a963
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/HoleRuntimeCorrespondenceTests.cs
@@ -0,0 +1,144 @@
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class HoleRuntimeCorrespondenceTests
+{
+ private static string Source(double diameter, double x = 0) => $"Model HoleWitness {{ Units: mm Box Body {{ Size: [40mm, 30mm, 8mm] }} Modify Body {{ Hole<Shaft> H {{ On: +Z Center: Point2({x}mm, 0mm) Diameter: {diameter}mm End: ThroughAll }} }} }}";
+ private static string WithWallDiameter(string source, string holeName = "H") => source[..^1] + $" Pmi {{ HoleDiameter WallDiameter {{ Target: face({holeName}.Wall) Value: 6mm }} }} }}";
+
+ [Fact]
+ public void SimpleThroughHoleCarriesWallAndRimsFromConstructionToDirectDisplay()
+ {
+ var build = FirmamentBuildAndExport.CompileSource(Source(6));
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(d => d.Message)));
+ var body = Assert.IsType<Aetheris.Kernel.Core.Brep.BrepBody>(build.Value.RuntimeBody);
+ var correspondence = Assert.IsType<SemanticTopologyCorrespondence>(build.Value.RuntimeCorrespondence);
+ var wall = Assert.Single(correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);
+ var sourceMap = new GeometrySourceMap(correspondence);
+ Assert.True(sourceMap.TryGetSourceSpan("Body.H", out var holeSpan));
+ Assert.Contains("Hole<Shaft> H", Source(6).Substring(holeSpan.Start, holeSpan.Length));
+ Assert.True(sourceMap.TryGetByBrepFace(wall.Face!.Value, out var mappedWall));
+ Assert.Equal(wall, mappedWall);
+ Assert.Contains(wall, sourceMap.GetEntitiesForSourceSymbol("Body.H"));
+ Assert.Equal("hole:Body.H", wall.SourceStableId);
+ Assert.Contains(body.Topology.Faces, face => face.Id == wall.Face);
+ Assert.Contains(correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleEntryLoop);
+ Assert.Contains(correspondence.Descendants, d => d.Role == SemanticTopologyRole.HoleExitLoop);
+ Assert.Equal(wall.StableId, Assert.Single(FirmamentBuildAndExport.CompileSource(Source(8)).Value.RuntimeCorrespondence!.Descendants,
+ d => d.Role == SemanticTopologyRole.HoleWallFace).StableId);
+ Assert.True(Step242Importer.ImportBody(build.Value.StepText).IsSuccess);
+ }
+
+ [Fact]
+ public void BoxTopTessellationCoversTheFullRectangle()
+ {
+ var build = FirmamentBuildAndExport.CompileSource("Model BoxWitness { Units: mm Box Body { Size: [40mm, 30mm, 8mm] } }");
+ Assert.True(build.IsSuccess);
+ var body = build.Value.RuntimeBody!;
+ var top = Assert.Single(build.Value.RuntimeCorrespondence!.Descendants, d => d.FirmamentSelector == "face(+Z)");
+ var mesh = BrepDisplayTessellator.Tessellate(body);
+ Assert.True(mesh.IsSuccess, string.Join("; ", mesh.Diagnostics.Select(d => d.Message)));
+ var patch = Assert.Single(mesh.Value.FacePatches, p => p.FaceId == top.Face);
+ Assert.True(patch.TriangleIndices.Count >= 6, $"top triangles={patch.TriangleIndices.Count / 3}, positions={string.Join(';', patch.Positions)}");
+ var area = 0d;
+ for (var i = 0; i < patch.TriangleIndices.Count; i += 3)
+ {
+ var a = patch.Positions[patch.TriangleIndices[i]];
+ var b = patch.Positions[patch.TriangleIndices[i + 1]];
+ var c = patch.Positions[patch.TriangleIndices[i + 2]];
+ area += Math.Abs((b.X - a.X) * (c.Y - a.Y) - (b.Y - a.Y) * (c.X - a.X)) / 2;
+ }
+ Assert.True(Math.Abs(area - 1200) < 1e-6, $"top area={area}, triangles={string.Join(',', patch.TriangleIndices)}, positions={string.Join(';', patch.Positions)}, vertices={string.Join(';', body.Topology.Vertices.Select(v => body.TryGetVertexPoint(v.Id, out var p) ? p.ToString() : "missing"))}");
+ }
+
+ [Fact]
+ public void ExistingAdvancedHoleSelectionDeclarationIsNotAcceptedInSimpleHoleSource()
+ {
+ var source = Source(6);
+ source = source[..^1] + " Selection WallH { Target: HoleWall Source: Hole(H) Require: NonEmptyFaceSet } }";
+ var build = FirmamentBuildAndExport.CompileSource(source);
+ Assert.False(build.IsSuccess);
+ Assert.Contains(build.Diagnostics, d => d.Message.Contains("firmament-v2-phase3-edge-finish-syntax-invalid", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void HoleWallSelectorParsesBindsAndResolvesToConstructionWall()
+ {
+ var source = WithWallDiameter(Source(6));
+ var parsed = FirmamentV2.FirmamentV2Parser.Parse(source);
+ Assert.True(parsed.IsSuccess, string.Join("; ", parsed.Diagnostics));
+ var selector = Assert.IsType<FirmamentV2.FirmamentV2HoleWallSelector>(Assert.Single(parsed.Document!.BoundPmi!.Dimensions).HoleWallTarget);
+ Assert.Equal("H", selector.HoleName);
+ Assert.Equal("Body", selector.BodyName);
+ var build = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(d => d.Message)));
+ var wall = Assert.Single(build.Value.RuntimeCorrespondence!.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);
+ Assert.Equal("face(H.Wall)", wall.FirmamentSelector);
+ Assert.Equal("hole:Body.H", wall.SourceStableId);
+ Assert.True(FirmamentV2.FirmamentV2HoleWallSelector.TryParse(wall.FirmamentSelector!, out var parsedHole));
+ Assert.Equal(selector.HoleName, parsedHole);
+ Assert.True(Step242Importer.ImportBody(build.Value.StepText).IsSuccess);
+ }
+
+ [Fact]
+ public void HoleWallSelectorSurvivesDiameterAndPositionEditsAndRenameChangesSpelling()
+ {
+ var initial = Assert.Single(FirmamentBuildAndExport.CompileSource(WithWallDiameter(Source(6))).Value.RuntimeCorrespondence!.Descendants,
+ d => d.Role == SemanticTopologyRole.HoleWallFace);
+ var edited = FirmamentBuildAndExport.CompileSource(WithWallDiameter(Source(7, 3)));
+ Assert.True(edited.IsSuccess, string.Join("; ", edited.Diagnostics.Select(d => d.Message)));
+ var editedWall = Assert.Single(edited.Value.RuntimeCorrespondence!.Descendants, d => d.Role == SemanticTopologyRole.HoleWallFace);
+ Assert.Equal(initial.StableId, editedWall.StableId);
+ Assert.Equal(initial.FirmamentSelector, editedWall.FirmamentSelector);
+ var renamed = WithWallDiameter(Source(6).Replace(" H {", " MountHole {", StringComparison.Ordinal), "MountHole");
+ var renamedBuild = FirmamentBuildAndExport.CompileSource(renamed);
+ Assert.True(renamedBuild.IsSuccess, string.Join("; ", renamedBuild.Diagnostics.Select(d => d.Message)));
+ Assert.Equal("face(MountHole.Wall)", Assert.Single(renamedBuild.Value.RuntimeCorrespondence!.Descendants,
+ d => d.Role == SemanticTopologyRole.HoleWallFace).FirmamentSelector);
+ }
+
+ [Fact]
+ public void DeletedAndNonHoleTargetsGetSpecificDiagnostics()
+ {
+ var deleted = FirmamentBuildAndExport.CompileSource(WithWallDiameter("Model HoleWitness { Units: mm Box Body { Size: [40mm, 30mm, 8mm] } }"));
+ Assert.False(deleted.IsSuccess);
+ Assert.Contains(deleted.Diagnostics, d => d.Message.Contains("firmament-v2-hole-wall-unknown-hole:H", StringComparison.Ordinal));
+ var nonHole = FirmamentBuildAndExport.CompileSource(WithWallDiameter(Source(6), "Body"));
+ Assert.False(nonHole.IsSuccess);
+ Assert.Contains(nonHole.Diagnostics, d => d.Message.Contains("firmament-v2-hole-wall-target-not-hole:Body", StringComparison.Ordinal));
+ var blind = FirmamentBuildAndExport.CompileSource(WithWallDiameter(Source(6).Replace("End: ThroughAll", "End: Blind 4mm", StringComparison.Ordinal)));
+ Assert.False(blind.IsSuccess);
+ Assert.Contains(blind.Diagnostics, d => d.Message.Contains("firmament-v2-hole-wall-role-unavailable:H", StringComparison.Ordinal));
+ var invalidDatum = FirmamentBuildAndExport.CompileSource(Source(6)[..^1]
+ + " Pmi { Datum CylindricalWall { Target: face(H.Wall) } } }");
+ Assert.False(invalidDatum.IsSuccess);
+ Assert.Contains(invalidDatum.Diagnostics, d => d.Message.Contains("firmament-v2-hole-wall-consumer-invalid:CylindricalWall", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void TwoNamedHolesBindDistinctWallRoles()
+ {
+ var source = "Model TwinHoles { Units: mm Box Body { Size: [40mm, 30mm, 8mm] } "
+ + "Modify Body { Hole<Shaft> H1 { On: +Z Center: Point2(-10mm, 0mm) Diameter: 6mm End: ThroughAll } "
+ + "Hole<Shaft> H2 { On: +Z Center: Point2(10mm, 0mm) Diameter: 6mm End: ThroughAll } } "
+ + "Pmi { HoleDiameter D1 { Target: face(H1.Wall) Value: 6mm } HoleDiameter D2 { Target: face(H2.Wall) Value: 6mm } } }";
+ var build = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(build.IsSuccess, string.Join("; ", build.Diagnostics.Select(d => d.Message)));
+ var correspondence = Assert.IsType<SemanticTopologyCorrespondence>(build.Value.RuntimeCorrespondence);
+ var walls = correspondence.Descendants.Where(d => d.Role == SemanticTopologyRole.HoleWallFace).ToArray();
+ Assert.Equal(2, walls.Length);
+ Assert.Equal(2, walls.Select(d => d.Face).Distinct().Count());
+ Assert.Equal(new[] { "face(H1.Wall)", "face(H2.Wall)" }, walls.Select(d => d.FirmamentSelector));
+ var map = new GeometrySourceMap(correspondence);
+ foreach (var wall in walls)
+ {
+ Assert.True(map.TryGetByBrepFace(wall.Face!.Value, out var mapped));
+ Assert.Equal(wall, mapped);
+ Assert.True(map.TryGetSourceSpan(wall.ParentStableId!, out _));
+ }
+ Assert.True(Step242Importer.ImportBody(build.Value.StepText).IsSuccess);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs b/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
index c56067a8..6bee5059 100644
--- a/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
@@ -7,6 +7,58 @@ namespace Aetheris.Kernel.Firmament.Tests;
public sealed class WireFormTests
{
+ [Fact]
+ public void Helix_AndAxisCoilShareSemanticIdentityAndGeometry()
+ {
+ var legacy = File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament"));
+ var canonical = legacy.Replace("AxisCoil Winding", "Helix Winding", StringComparison.Ordinal);
+ var helixResult = WireFormAuthoring.Parse(canonical);
+ var legacyResult = WireFormAuthoring.Parse(legacy);
+ Assert.True(helixResult.IsSuccess);
+ Assert.True(legacyResult.IsSuccess);
+ var helix = Assert.IsType<WireAxisCoilAir>(Assert.Single(helixResult.Value.Operations));
+ var axisCoil = Assert.IsType<WireAxisCoilAir>(Assert.Single(legacyResult.Value.Operations));
+ Assert.Equal("Helix", helix.CoilKind);
+ Assert.Equal(axisCoil, helix);
+ Assert.Equal(axisCoil.StableId(legacyResult.Value.Name), helix.StableId(helixResult.Value.Name));
+ for (var sample = 0; sample <= 32; sample++)
+ Assert.True((helix.Evaluate(sample / 32d) - axisCoil.Evaluate(sample / 32d)).Length < 1e-12);
+ var built = FirmamentBuildAndExport.CompileSource(canonical);
+ Assert.True(built.IsSuccess, Messages(built));
+ Assert.Equal("Helix", Assert.Single(built.Value.WireForm!.Operations).Kind);
+ }
+
+ [Theory]
+ [InlineData("Radius: 12mm", "Radius: -12mm", "wireform-coil-radius-invalid")]
+ [InlineData("Pitch: 5mm", "Pitch: -5mm", "wireform-coil-parameters-inconsistent")]
+ [InlineData("Pitch: 5mm", "", "wireform-coil-parameters-inconsistent")]
+ [InlineData("Pitch: 5mm", "Pitch: 5mm; Height: 39mm", "wireform-coil-parameters-inconsistent")]
+ public void Helix_RejectsInvalidOrInconsistentDimensions(string oldText, string newText, string code)
+ {
+ var source = File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament"))
+ .Replace("AxisCoil Winding", "Helix Winding", StringComparison.Ordinal)
+ .Replace(oldText, newText, StringComparison.Ordinal);
+ var result = WireFormAuthoring.Parse(source);
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Message.Contains(code, StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void Helix_DerivesPitchFromHeightAndKeepsExplicitHandedness()
+ {
+ var source = File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament"))
+ .Replace("AxisCoil Winding", "Helix Winding", StringComparison.Ordinal)
+ .Replace("Pitch: 5mm", "Height: 40mm", StringComparison.Ordinal)
+ .Replace("RightHanded", "LeftHanded", StringComparison.Ordinal);
+ var result = WireFormAuthoring.Parse(source);
+ Assert.True(result.IsSuccess);
+ var helix = Assert.IsType<WireAxisCoilAir>(Assert.Single(result.Value.Operations));
+ Assert.Equal(8d, helix.Turns);
+ Assert.Equal(5d, helix.PitchMm);
+ Assert.Equal(40d, helix.HeightMm);
+ Assert.Equal(WireCoilHandedness.LeftHanded, helix.Handedness);
+ }
+
[Fact]
[Trait("Category", "SlowCorpus")]
public void AxisCoil_LowersSemanticHelixToNonRationalSplineTube()
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
index b33b4fcf..3589e622 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs
@@ -304,7 +304,9 @@ internal static class FirmamentPlacementResolver
if (curve.Kind == CurveGeometryKind.Line3)
{
var line = curve.Line3!.Value;
- point = edge.StartVertexId == vertexId ? line.Evaluate(0d) : line.Evaluate(1d);
+ if (!body.Bindings.TryGetEdgeBinding(edge.Id, out var binding) || binding.TrimInterval is not { } trim)
+ continue;
+ point = edge.StartVertexId == vertexId ? line.Evaluate(trim.Start) : line.Evaluate(trim.End);
return true;
}
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
index 5780d2c0..8c654d9f 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutionResult.cs
@@ -1,5 +1,6 @@
using Aetheris.Kernel.Core.Brep;
using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Brep.Features;
using Aetheris.Kernel.Firmament.Lowering;
namespace Aetheris.Kernel.Firmament.Execution;
@@ -13,7 +14,8 @@ public sealed record FirmamentExecutedPrimitive(
int OpIndex,
string FeatureId,
FirmamentLoweredPrimitiveKind Kind,
- BrepBody Body);
+ BrepBody Body,
+ BrepExtrudeConstructionTopology? BoxConstructionTopology = null);
public sealed record FirmamentExecutedBoolean(
int OpIndex,
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index 1d439393..9dfbea72 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -48,7 +48,7 @@ internal static class FirmamentPrimitiveExecutor
return KernelResult<FirmamentPrimitiveExecutionResult>.Failure(bodyResult.Diagnostics);
}
- executedPrimitives.Add(new FirmamentExecutedPrimitive(primitive.OpIndex, primitive.FeatureId, primitive.Kind, bodyResult.Value.Published));
+ executedPrimitives.Add(new FirmamentExecutedPrimitive(primitive.OpIndex, primitive.FeatureId, primitive.Kind, bodyResult.Value.Published, bodyResult.Value.BoxConstructionTopology));
resolvedPlacementByOpIndex[primitive.OpIndex] = BuildResolvedPlacement(primitive.Placement, bodyResult.Value.PlacementTranslation);
publishedBodiesByFeatureId[primitive.FeatureId] = bodyResult.Value.Published;
booleanExecutionBodiesByFeatureId[primitive.FeatureId] = bodyResult.Value.LegacyForBoolean;
@@ -591,7 +591,7 @@ internal static class FirmamentPrimitiveExecutor
private static KernelResult<FirmamentExecutedPrimitiveBodies> ExecutePrimitive(FirmamentLoweredPrimitive primitive, IReadOnlyDictionary<string, BrepBody> publishedBodies)
{
- var legacyResult = ExecuteLegacyPrimitive(primitive);
+ var legacyResult = ExecuteLegacyPrimitive(primitive, out var boxTopology);
if (!legacyResult.IsSuccess)
{
return KernelResult<FirmamentExecutedPrimitiveBodies>.Failure(legacyResult.Diagnostics);
@@ -605,7 +605,7 @@ internal static class FirmamentPrimitiveExecutor
}
var publishedBody = TranslateBody(defaultFrameBody, placementResult.Value);
- return KernelResult<FirmamentExecutedPrimitiveBodies>.Success(new FirmamentExecutedPrimitiveBodies(publishedBody, legacyResult.Value, placementResult.Value));
+ return KernelResult<FirmamentExecutedPrimitiveBodies>.Success(new FirmamentExecutedPrimitiveBodies(publishedBody, legacyResult.Value, placementResult.Value, boxTopology));
}
private static BrepBody ApplyDefaultLocalFrame(FirmamentLoweredPrimitive primitive, BrepBody body)
@@ -627,11 +627,17 @@ internal static class FirmamentPrimitiveExecutor
};
}
- private static KernelResult<BrepBody> ExecuteLegacyPrimitive(FirmamentLoweredPrimitive primitive)
+ private static KernelResult<BrepBody> ExecuteLegacyPrimitive(FirmamentLoweredPrimitive primitive,
+ out BrepExtrudeConstructionTopology? boxTopology)
{
+ boxTopology = null;
+ if (primitive.Kind == FirmamentLoweredPrimitiveKind.Box)
+ {
+ var box = (FirmamentLoweredBoxParameters)primitive.Parameters;
+ return BrepPrimitives.CreateBoxWithTopology(box.SizeX, box.SizeY, box.SizeZ, out boxTopology);
+ }
return primitive.Kind switch
{
- FirmamentLoweredPrimitiveKind.Box => BrepPrimitives.CreateBox(((FirmamentLoweredBoxParameters)primitive.Parameters).SizeX, ((FirmamentLoweredBoxParameters)primitive.Parameters).SizeY, ((FirmamentLoweredBoxParameters)primitive.Parameters).SizeZ),
FirmamentLoweredPrimitiveKind.Cylinder => BrepPrimitives.CreateCylinder(((FirmamentLoweredCylinderParameters)primitive.Parameters).Radius, ((FirmamentLoweredCylinderParameters)primitive.Parameters).Height),
FirmamentLoweredPrimitiveKind.Cone => ExecuteCone((FirmamentLoweredConeParameters)primitive.Parameters),
FirmamentLoweredPrimitiveKind.Torus => BrepPrimitives.CreateTorus(((FirmamentLoweredTorusParameters)primitive.Parameters).MajorRadius, ((FirmamentLoweredTorusParameters)primitive.Parameters).MinorRadius),
@@ -1498,7 +1504,8 @@ internal static class FirmamentPrimitiveExecutor
=> FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);
}
-internal sealed record FirmamentExecutedPrimitiveBodies(BrepBody Published, BrepBody LegacyForBoolean, Vector3D PlacementTranslation);
+internal sealed record FirmamentExecutedPrimitiveBodies(BrepBody Published, BrepBody LegacyForBoolean, Vector3D PlacementTranslation,
+ BrepExtrudeConstructionTopology? BoxConstructionTopology = null);
internal static class FirmamentPrimitiveToolParsing
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 2dec239e..68d0a154 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -15,6 +15,7 @@ using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Numerics;
using Aetheris.Kernel.Core.Topology;
using Aetheris.Kernel.Firmament.Execution;
+using Aetheris.Kernel.Firmament.Lowering;
using Aetheris.Kernel.Firmament.FirmamentV2;
using Aetheris.Kernel.Firmament.Materializer;
using Aetheris.Kernel.StandardLibrary;
@@ -387,7 +388,7 @@ public static class FirmamentBuildAndExport
return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, authored.Value.Name, 0,
"wire-form", "wireform", WireForm: report,
EngineeringFeatures: authored.Value.Operations.Select(operation => new FirmamentEngineeringFeatureReport(
- operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "AxisCoil", WireSurfaceCoilAir => "SurfaceCoil", WireKnotPathAir => "KnotPath", _ => "Unknown" }, operation.StableId(authored.Value.Name),
+ operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "Helix", WireSurfaceCoilAir => "SurfaceCoil", WireKnotPathAir => "KnotPath", _ => "Unknown" }, operation.StableId(authored.Value.Name),
authored.Value.Name, "WireState", "CircularSection", operation.LengthMm, "CenterlineLength", "Add",
PolicySource: "WireFormFeatureAir", MaterializationRoute: "WireFormCenterlineAir->CircularSweepBRepPlan")).ToArray()), []);
}
@@ -577,15 +578,25 @@ public static class FirmamentBuildAndExport
return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
}
- return KernelResult<FirmamentStepExportResult>.Success(
- new FirmamentStepExportResult(
+ var primitiveExport = new FirmamentStepExportResult(
step.Value,
executedPrimitive.FeatureId,
executedPrimitive.OpIndex,
"primitive",
v2Parse.Document.Solid.RecordType.ToLowerInvariant(),
DatumInspection: v2Parse.Document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.DatumPlane).Select(p => new FirmamentPmiInspectionDatum(p.Name, "planar", p.Target)).ToArray() ?? [],
- DimensionInspection: []));
+ DimensionInspection: []);
+ if (executedPrimitive.Kind == FirmamentLoweredPrimitiveKind.Box
+ && executedPrimitive.BoxConstructionTopology is { } boxTopology
+ && v2Parse.Document.Solids.Count == 1
+ && execution.Value.ExecutedBooleans.Count == 0)
+ primitiveExport = primitiveExport with
+ {
+ RuntimeBody = executedPrimitive.Body,
+ RuntimeCorrespondence = BoxConstructionCorrespondence.Create(executedPrimitive.FeatureId, boxTopology,
+ v2Parse.Document.Solids.Single(s => s.Name == executedPrimitive.FeatureId).SourceSpan)
+ };
+ return KernelResult<FirmamentStepExportResult>.Success(primitiveExport);
}
if (v2Parse.Diagnostics.Contains(FirmamentV2Parser.InlineStepRequiresCanonical, StringComparer.Ordinal))
@@ -2058,11 +2069,13 @@ public static class FirmamentBuildAndExport
// The stock frame is authored by the Box, never inferred from ConceptIr presence.
var host = FirmamentStockFrame.ForBox(box.Size[0], box.Size[1], box.Size[2]).CreateHoleHost();
Aetheris.Kernel.Core.Brep.BrepBody? body;
+ SemanticTopologyCorrespondence? runtimeCorrespondence = null;
IReadOnlyList<string> diagnostics;
if (semanticHoles.Count == 1)
{
var materialized = AirHoleSimpleShaftMaterializer.Execute(feature, host);
body = materialized.Body;
+ runtimeCorrespondence = materialized.Correspondence;
diagnostics = materialized.Diagnostics;
if (!materialized.Succeeded || body is null)
{
@@ -2073,6 +2086,7 @@ public static class FirmamentBuildAndExport
{
var materialized = AirHoleCompositeMaterializer.Execute(semanticHoles, host);
body = materialized.Body;
+ runtimeCorrespondence = materialized.Correspondence;
diagnostics = materialized.Diagnostics;
if (!materialized.Succeeded || body is null)
{
@@ -2080,7 +2094,42 @@ public static class FirmamentBuildAndExport
}
}
- var semanticPmi = BuildV2SemanticPmi(document, semanticHoles, modifyTargets[0]);
+ if (runtimeCorrespondence is not null)
+ {
+ var sourceSpans = new Dictionary<string, FirmamentV2SourceSpan>(StringComparer.Ordinal);
+ if (targetSolid.SourceSpan is { } bodySpan) sourceSpans[modifyTargets[0]] = bodySpan;
+ foreach (var modify in document.ModifyBlocks)
+ foreach (var hole in modify.SemanticHoles)
+ if (hole.SourceSpan is { } holeSpan) sourceSpans[$"{modify.TargetSolid}.{hole.Name}"] = holeSpan;
+ runtimeCorrespondence = runtimeCorrespondence with
+ {
+ SourceSpans = sourceSpans,
+ Descendants = runtimeCorrespondence.Descendants.Select(descendant =>
+ {
+ var owner = semanticHoles.FirstOrDefault(hole => descendant.SourceStableId == $"hole:{hole.FeatureId}");
+ return descendant with
+ {
+ FirmamentSelector = owner is null ? descendant.FirmamentSelector
+ : FirmamentV2HoleWallSelector.Format(descendant, owner.Name, owner.FeatureId) ?? descendant.FirmamentSelector
+ };
+ }).ToArray()
+ };
+ }
+ foreach (var pmi in document.BoundPmi?.Dimensions ?? [])
+ {
+ if (pmi.HoleWallTarget is not { } selector) continue;
+ if (runtimeCorrespondence is null || body is null || selector.BodyName != runtimeCorrespondence.BodyStableId)
+ return SemanticHoleFailure([$"firmament-v2-hole-wall-role-unavailable:{selector.HoleName}"]);
+ var selectedFeature = semanticHoles.SingleOrDefault(hole => hole.Name == selector.HoleName);
+ if (selectedFeature is null) return SemanticHoleFailure([$"firmament-v2-hole-wall-unknown-hole:{selector.HoleName}"]);
+ var request = new SemanticSelectionRequest($"pmi:{pmi.Name}", pmi.Name, selector.BodyName,
+ [$"hole:{selectedFeature.FeatureId}"], SemanticTopologyRole.HoleWallFace,
+ SemanticSelectionRequirement.NonEmptyFaceSet, $"offset:{pmi.SourceSpan.Start}", "HoleDiameter");
+ var resolution = SemanticTopologySelectionResolver.Resolve(body, runtimeCorrespondence, request);
+ if (!resolution.Succeeded)
+ return SemanticHoleFailure([$"firmament-v2-hole-wall-role-unavailable:{selector.HoleName}:{resolution.Failure}"]);
+ }
+ var semanticPmi = BuildV2SemanticPmi(document, semanticHoles, modifyTargets[0], correspondence: runtimeCorrespondence);
// Semantic-hole/profile-stack and bounded-Boolean routes remain Audit until their
// historical coincident/seam topology is remediated producer-by-producer.
var step = Step242Exporter.ExportBody(body, semanticPmi);
@@ -2138,7 +2187,11 @@ public static class FirmamentBuildAndExport
DatumInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.DatumPlane).Select(p => new FirmamentPmiInspectionDatum(p.Name, "planar", p.Target)).ToArray() ?? [],
DimensionInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.HoleDiameter).Select(p => new FirmamentPmiInspectionDimension("Diameter", p.Target, null, p.Value ?? 0d, "explicit-v2-semantic-pmi", p.Name)).ToArray() ?? [],
ConceptIr: document.ConceptIr,
- Features: featureReports));
+ Features: featureReports)
+ {
+ RuntimeBody = runtimeCorrespondence is null ? null : body,
+ RuntimeCorrespondence = runtimeCorrespondence
+ });
}
private static KernelResult<bool> ValidateV2PmiExportSupport(FirmamentV2Document document)
@@ -2179,7 +2232,11 @@ public static class FirmamentBuildAndExport
boundPmiByName.TryGetValue(pmi.Name, out var boundPmi);
var tolerancePlus = boundPmi?.DimensionTolerance?.Plus;
var toleranceMinus = boundPmi?.DimensionTolerance?.Minus;
- if (holeByName.TryGetValue(pmi.Target, out var pmiHole))
+ if (boundPmi?.HoleWallTarget is { } wallTarget && holeByName.TryGetValue(wallTarget.HoleName, out var wallHole))
+ {
+ result.Add(new Step242SemanticPmiHole(wallHole.FeatureId, pmi.Value.Value, null, "explicit_v2_hole_wall_diameter", tolerancePlus, toleranceMinus));
+ }
+ else if (holeByName.TryGetValue(pmi.Target, out var pmiHole))
{
result.Add(new Step242SemanticPmiHole(pmiHole.FeatureId, pmi.Value.Value, null, "explicit_v2_semantic_hole_diameter", tolerancePlus, toleranceMinus));
}
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 5be3bf4b..038d7798 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -1,3 +1,7 @@
+using System.Text.Json.Serialization;
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Firmament.Materializer;
+
namespace Aetheris.Kernel.Firmament;
public sealed record FirmamentStepExportResult(
@@ -29,7 +33,13 @@ public sealed record FirmamentStepExportResult(
Aetheris.Kernel.Firmament.Piping.PipingReport? Piping = null,
FirmamentRevolveReport? Revolve = null,
FirmamentGearReport? Gear = null,
- Aetheris.Kernel.Firmament.FirmamentV2.FirmamentPlateauReport? Plateau = null);
+ Aetheris.Kernel.Firmament.FirmamentV2.FirmamentPlateauReport? Plateau = null)
+{
+ // In-process display can use the exact body that was exported to STEP.
+ // It is intentionally absent from CLI/JSON artifact serialization.
+ [JsonIgnore] public BrepBody? RuntimeBody { get; init; }
+ [JsonIgnore] public SemanticTopologyCorrespondence? RuntimeCorrespondence { get; init; }
+}
public sealed record FirmamentGearItemReport(
string Name,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
index 9b7578cd..8a45b99a 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
@@ -48,7 +48,7 @@ public enum FirmamentV2ConstructionPolicy { Solid, Hollow }
/// <summary>Source-owned hollow intent. This is deliberately not a Boolean tool description.</summary>
public sealed record FirmamentV2HollowIntent(double WallThickness, IReadOnlyList<string> Openings, FirmamentV2SourceSpan SourceSpan);
-public sealed record FirmamentV2SolidBinding(string Name, string RecordType, FirmamentV2PrimitiveRecord Primitive, string? DerivedFrom = null, IReadOnlyDictionary<string, IReadOnlyList<double>>? Overrides = null, IReadOnlyDictionary<string, string>? Provenance = null, FirmamentV2ConstructionPolicy ConstructionPolicy = FirmamentV2ConstructionPolicy.Solid, FirmamentV2HollowIntent? Hollow = null)
+public sealed record FirmamentV2SolidBinding(string Name, string RecordType, FirmamentV2PrimitiveRecord Primitive, string? DerivedFrom = null, IReadOnlyDictionary<string, IReadOnlyList<double>>? Overrides = null, IReadOnlyDictionary<string, string>? Provenance = null, FirmamentV2ConstructionPolicy ConstructionPolicy = FirmamentV2ConstructionPolicy.Solid, FirmamentV2HollowIntent? Hollow = null, FirmamentV2SourceSpan? SourceSpan = null)
{
public bool IsDerived => !string.IsNullOrWhiteSpace(DerivedFrom);
public FirmamentV2BoxRecord? Box => Primitive as FirmamentV2BoxRecord;
@@ -254,7 +254,7 @@ public sealed record FirmamentV2PmiBlock(IReadOnlyList<FirmamentV2PmiRecord> Rec
public sealed record FirmamentV2PmiRecord(FirmamentV2PmiKind Kind, string Name, IReadOnlyDictionary<string, FirmamentV2PmiField> Fields, FirmamentV2SourceSpan SourceSpan, FirmamentV2BoundPmiRecord? Bound = null, FirmamentV2PmiProjection? Projection = null);
public sealed record FirmamentV2PmiField(string Name, string Source, FirmamentV2SourceSpan SourceSpan, FirmamentV2ValueExpression? ValueExpression = null);
public sealed record FirmamentV2BoundPmiBlock(IReadOnlyList<FirmamentV2BoundPmiRecord> Datums, IReadOnlyList<FirmamentV2BoundPmiRecord> Dimensions, IReadOnlyList<FirmamentV2BoundPmiRecord> Controls, IReadOnlyList<string> Diagnostics);
-public sealed record FirmamentV2BoundPmiRecord(FirmamentV2PmiKind Kind, string Name, IReadOnlyList<string> Targets, FirmamentV2LiteralValue? DimensionValue, FirmamentV2Tolerance? DimensionTolerance, FirmamentV2LiteralValue? ControlTolerance, IReadOnlyList<string> DatumRefs, FirmamentV2SourceSpan SourceSpan, string? ProjectionSource = null);
+public sealed record FirmamentV2BoundPmiRecord(FirmamentV2PmiKind Kind, string Name, IReadOnlyList<string> Targets, FirmamentV2LiteralValue? DimensionValue, FirmamentV2Tolerance? DimensionTolerance, FirmamentV2LiteralValue? ControlTolerance, IReadOnlyList<string> DatumRefs, FirmamentV2SourceSpan SourceSpan, string? ProjectionSource = null, FirmamentV2HoleWallSelector? HoleWallTarget = null);
/// <summary>Reusable, validated dimensional intent. Only equality of a semantic feature property
/// to a length expectation is admitted in Preview 1.</summary>
public sealed record FirmamentV2SemanticConstraint(string Id, string Subject, string Property, FirmamentV2LiteralValue NominalValue, FirmamentV2Tolerance? Tolerance, bool ValidationSucceeded, FirmamentV2SourceSpan SourceSpan, string ExpectedProvenance);
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2HoleWallSelector.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2HoleWallSelector.cs
new file mode 100644
index 00000000..015ff841
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2HoleWallSelector.cs
@@ -0,0 +1,26 @@
+using System.Text.RegularExpressions;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+/// <summary>The single canonical source spelling for a named Hole's wall output.</summary>
+public sealed record FirmamentV2HoleWallSelector(string HoleName, string BodyName)
+{
+ private static readonly Regex Syntax = new(@"^face\((?<hole>[A-Za-z_][A-Za-z0-9_]*)\.Wall\)$", RegexOptions.CultureInvariant);
+
+ public static bool TryParse(string text, out string holeName)
+ {
+ var match = Syntax.Match(text);
+ holeName = match.Success ? match.Groups["hole"].Value : string.Empty;
+ return match.Success;
+ }
+
+ public static string Format(string holeName) => $"face({holeName}.Wall)";
+
+ public static string? Format(SemanticTopologyDescendant descendant, string holeName, string featureId) =>
+ descendant.Role == SemanticTopologyRole.HoleWallFace
+ && descendant.Face.HasValue
+ && descendant.SourceStableId == $"hole:{featureId}"
+ && descendant.Addressability is SemanticTopologyAddressability.AuthoredStable or SemanticTopologyAddressability.DerivedStable
+ ? Format(holeName) : null;
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 85c8bbc8..a5c0c6c1 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -180,6 +180,10 @@ public static class FirmamentV2Parser
public const string PmiKindUnknown = "firmament-v2-pmi-kind-unknown";
public const string PmiTargetMissing = "firmament-v2-pmi-target-missing";
public const string PmiTargetUnresolved = "firmament-v2-pmi-target-unresolved";
+ public const string HoleWallUnknownHole = "firmament-v2-hole-wall-unknown-hole";
+ public const string HoleWallNotHole = "firmament-v2-hole-wall-target-not-hole";
+ public const string HoleWallAmbiguous = "firmament-v2-hole-wall-ambiguous-hole";
+ public const string HoleWallConsumerInvalid = "firmament-v2-hole-wall-consumer-invalid";
public const string PmiDiameterInvalid = "firmament-v2-pmi-diameter-invalid";
public const string PmiDuplicateName = "firmament-v2-pmi-duplicate-name";
public const string PmiDuplicateBlock = "firmament-v2-pmi-duplicate-block";
@@ -1464,7 +1468,8 @@ public static class FirmamentV2Parser
var primitiveBody = body[(open + 1)..close];
var record = ParseCanonicalPrimitive(primitive.Groups["type"].Value, primitiveBody, diagnostics);
if (record is null) return CanonicalFailure(diagnostics, CanonicalPrimitiveMalformed);
- var solid = new FirmamentV2SolidBinding(name, primitive.Groups["type"].Value, record);
+ var solid = new FirmamentV2SolidBinding(name, primitive.Groups["type"].Value, record,
+ SourceSpan: new FirmamentV2SourceSpan(rootOpen + 1 + primitive.Index, close - primitive.Index + 1));
byName[name] = solid;
solids.Add(solid);
}
@@ -2069,7 +2074,7 @@ public static class FirmamentV2Parser
|| code.StartsWith(ConceptIrResolver.PointProjectionUnsupported, StringComparison.Ordinal)
|| code.StartsWith("firmament-static-", StringComparison.Ordinal);
- public static bool IsFatalDiagnosticCode(string code) => code.StartsWith(RevolveAuthoringParser.Prefix, StringComparison.Ordinal) || code.StartsWith(FirmamentV2FeatureExpansion.Prefix, StringComparison.Ordinal) || code.StartsWith("firmament-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-traceloop-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-segment-", StringComparison.Ordinal) || code.StartsWith("firmament-boss-", StringComparison.Ordinal) || code.StartsWith("firmament-pocket-", StringComparison.Ordinal) || code.StartsWith("feature-support-", StringComparison.Ordinal) || code.StartsWith("compose-role-cardinality:", StringComparison.Ordinal) || code.StartsWith(ModifyTargetNotBoundToActiveCompose, StringComparison.Ordinal) || code.StartsWith("firmament-v2-assert-volume-", StringComparison.Ordinal) || code.StartsWith(SemanticConstraintMalformed, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintUnsupported, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintDimensionMismatch, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintValidationFailed, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnknownRequire, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnsupportedKind, StringComparison.Ordinal) || code.StartsWith(PmiProjectedFieldMustNotOverrideSourceConstraint, StringComparison.Ordinal) || code.StartsWith(AssertVolumeKindUnsupported, StringComparison.Ordinal) || code.StartsWith(CanonicalDeclarationUnknown + ":", StringComparison.Ordinal) || code.StartsWith(CanonicalConstructNotYetSupported + ":", StringComparison.Ordinal) || code.StartsWith(EdgeFinishProfileComposeBoundaryUnsupported, StringComparison.Ordinal) || IsConceptFatalDiagnostic(code) || code is UnknownConstructionPolicy or PrimitiveDoesNotSatisfyHollowConstructible or WallThicknessRequired or WallThicknessMustBePositive or UnsupportedOpening or MultipleOpeningsNotSupported or Phase3EdgeFinishSyntaxInvalid or PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch or UnknownReplacementBody or UnknownReplacementRegion or ReplacementKindMismatch or ReplacementFaceUnresolved or ReplacementUnsupportedKind or ReplacementVerificationFailed or ReplacementRadiusInvalid or ReplacementEndUnsupported or LetDuplicateName or LetUnknownType or LetMismatch or LetInvalidLiteral or LetUnitMismatch or LetLiteralOnly or LetRecordDuplicateName or LetRecordDuplicateField or LetReferenceUnknownRecord or LetReferenceUnknownField or LetReferenceNonRecord or LetReferenceRecordUsedAsValue or ExpressionUnknownSymbol or ExpressionUnknownRecord or ExpressionUnknownField or ExpressionRecordUsedAsValue or ExpressionScalarUsedAsRecord or ExpressionTypeMismatch or ExpressionInvalidOperator or ExpressionDivisionByZero or ExpressionCycle or ExpressionUnsupported or ToleranceInvalidType or ToleranceUnitMismatch or ToleranceInvalidLiteral or ToleranceNegativeBilateral or ToleranceMissingMinus or ToleranceMissingPlus or ToleranceUnsupported or RecognitionEvidenceRadiusInvalid or RecognitionEvidenceSurfaceFamilyUnknown or RecognitionEvidenceAxisInvalid or SemanticProposalKindMismatch or SemanticProposalRadiusInvalid or SemanticProposalTargetUnresolved or SemanticProposalEndUnsupported or ConceptUnknownFamily or ConceptUnknownConcept or ConceptMissingRequiredField or ConceptUnknownField or ConceptDuplicateField or ConceptFieldTypeMismatch or ConceptInvalidTarget or ConceptDescriptorUnavailable or PmiDuplicateBlock or PmiDuplicateRecord or PmiDuplicateDatum or PmiUnknownRecordKind or PmiMissingRequiredField or PmiUnknownField or PmiDuplicateField or PmiInvalidTarget or PmiUnknownDatum or PmiDimensionTypeMismatch or PmiDimensionMissingTolerance or PmiToleranceTypeMismatch or StandaloneFillRegionRequired or UnsupportedStandaloneFillPattern or InvalidCellCount or CellSizeMustBePositive or StrutRadiusMustBePositive or NodeRadiusMustBePositive or MaterialBoundsMismatch or StandaloneFillMultipleUnsupported;
+ public static bool IsFatalDiagnosticCode(string code) => code.StartsWith("firmament-v2-hole-wall-", StringComparison.Ordinal) || code.StartsWith(RevolveAuthoringParser.Prefix, StringComparison.Ordinal) || code.StartsWith(FirmamentV2FeatureExpansion.Prefix, StringComparison.Ordinal) || code.StartsWith("firmament-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-traceloop-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-segment-", StringComparison.Ordinal) || code.StartsWith("firmament-boss-", StringComparison.Ordinal) || code.StartsWith("firmament-pocket-", StringComparison.Ordinal) || code.StartsWith("feature-support-", StringComparison.Ordinal) || code.StartsWith("compose-role-cardinality:", StringComparison.Ordinal) || code.StartsWith(ModifyTargetNotBoundToActiveCompose, StringComparison.Ordinal) || code.StartsWith("firmament-v2-assert-volume-", StringComparison.Ordinal) || code.StartsWith(SemanticConstraintMalformed, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintUnsupported, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintDimensionMismatch, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintValidationFailed, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnknownRequire, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnsupportedKind, StringComparison.Ordinal) || code.StartsWith(PmiProjectedFieldMustNotOverrideSourceConstraint, StringComparison.Ordinal) || code.StartsWith(AssertVolumeKindUnsupported, StringComparison.Ordinal) || code.StartsWith(CanonicalDeclarationUnknown + ":", StringComparison.Ordinal) || code.StartsWith(CanonicalConstructNotYetSupported + ":", StringComparison.Ordinal) || code.StartsWith(EdgeFinishProfileComposeBoundaryUnsupported, StringComparison.Ordinal) || IsConceptFatalDiagnostic(code) || code is UnknownConstructionPolicy or PrimitiveDoesNotSatisfyHollowConstructible or WallThicknessRequired or WallThicknessMustBePositive or UnsupportedOpening or MultipleOpeningsNotSupported or Phase3EdgeFinishSyntaxInvalid or PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch or UnknownReplacementBody or UnknownReplacementRegion or ReplacementKindMismatch or ReplacementFaceUnresolved or ReplacementUnsupportedKind or ReplacementVerificationFailed or ReplacementRadiusInvalid or ReplacementEndUnsupported or LetDuplicateName or LetUnknownType or LetMismatch or LetInvalidLiteral or LetUnitMismatch or LetLiteralOnly or LetRecordDuplicateName or LetRecordDuplicateField or LetReferenceUnknownRecord or LetReferenceUnknownField or LetReferenceNonRecord or LetReferenceRecordUsedAsValue or ExpressionUnknownSymbol or ExpressionUnknownRecord or ExpressionUnknownField or ExpressionRecordUsedAsValue or ExpressionScalarUsedAsRecord or ExpressionTypeMismatch or ExpressionInvalidOperator or ExpressionDivisionByZero or ExpressionCycle or ExpressionUnsupported or ToleranceInvalidType or ToleranceUnitMismatch or ToleranceInvalidLiteral or ToleranceNegativeBilateral or ToleranceMissingMinus or ToleranceMissingPlus or ToleranceUnsupported or RecognitionEvidenceRadiusInvalid or RecognitionEvidenceSurfaceFamilyUnknown or RecognitionEvidenceAxisInvalid or SemanticProposalKindMismatch or SemanticProposalRadiusInvalid or SemanticProposalTargetUnresolved or SemanticProposalEndUnsupported or ConceptUnknownFamily or ConceptUnknownConcept or ConceptMissingRequiredField or ConceptUnknownField or ConceptDuplicateField or ConceptFieldTypeMismatch or ConceptInvalidTarget or ConceptDescriptorUnavailable or PmiDuplicateBlock or PmiDuplicateRecord or PmiDuplicateDatum or PmiUnknownRecordKind or PmiMissingRequiredField or PmiUnknownField or PmiDuplicateField or PmiInvalidTarget or PmiUnknownDatum or PmiDimensionTypeMismatch or PmiDimensionMissingTolerance or PmiToleranceTypeMismatch or StandaloneFillRegionRequired or UnsupportedStandaloneFillPattern or InvalidCellCount or CellSizeMustBePositive or StrutRadiusMustBePositive or NodeRadiusMustBePositive or MaterialBoundsMismatch or StandaloneFillMultipleUnsupported;
private static IReadOnlyList<FirmamentV2Exposure> ParseExposures(string body, List<string> diagnostics)
{
@@ -2859,7 +2864,7 @@ public static class FirmamentV2Parser
ValidatePmiFieldSet(kindRaw, name, fields, diagnostics);
var record = new FirmamentV2PmiRecord(kind, name, fields, new FirmamentV2SourceSpan(open + 1 + em.Index, entryClose - em.Index + 1));
records.Add(record);
- if (!TryBindPmiRecord(record, solids, regionByTarget, aliases, holeNames, letMap, recordMap, knownDatums, diagnostics, out var b)) continue;
+ if (!TryBindPmiRecord(record, solids, modifyBlocks, regionByTarget, aliases, holeNames, letMap, recordMap, knownDatums, diagnostics, out var b)) continue;
bound.Add(b);
if (kind == FirmamentV2PmiKind.DatumPlane) knownDatums.Add(name);
if (kind is FirmamentV2PmiKind.DatumPlane or FirmamentV2PmiKind.HoleDiameter)
@@ -2928,12 +2933,25 @@ public static class FirmamentV2Parser
foreach (var f in fields.Keys) if (!allowed.Contains(f)) diagnostics.Add(PmiUnknownField);
}
- private static bool TryBindPmiRecord(FirmamentV2PmiRecord r, Dictionary<string,FirmamentV2SolidBinding> solids, IReadOnlyDictionary<string,FirmamentV2RecognizedRegion> regions, HashSet<string> aliases, HashSet<string> holeNames, IReadOnlyDictionary<string,FirmamentV2BoundLet> lets, IReadOnlyDictionary<string,FirmamentV2BoundLetRecord> records, HashSet<string> datums, List<string> diagnostics, out FirmamentV2BoundPmiRecord bound)
+ private static bool TryBindPmiRecord(FirmamentV2PmiRecord r, Dictionary<string,FirmamentV2SolidBinding> solids, IReadOnlyList<FirmamentV2ModifyBlock> modifyBlocks, IReadOnlyDictionary<string,FirmamentV2RecognizedRegion> regions, HashSet<string> aliases, HashSet<string> holeNames, IReadOnlyDictionary<string,FirmamentV2BoundLet> lets, IReadOnlyDictionary<string,FirmamentV2BoundLetRecord> records, HashSet<string> datums, List<string> diagnostics, out FirmamentV2BoundPmiRecord bound)
{
bound=null!;
string? target = Field(r,"target"); string? targetA=Field(r,"targetA"); string? targetB=Field(r,"targetB");
var targets = new[]{target,targetA,targetB}.Where(t=>t is not null).Cast<string>().ToArray();
- foreach (var t in targets) ValidateTarget(t, r.Kind, solids, regions, aliases, holeNames, diagnostics);
+ FirmamentV2HoleWallSelector? wallTarget = null;
+ foreach (var t in targets)
+ {
+ if (!FirmamentV2HoleWallSelector.TryParse(t, out var holeName))
+ {
+ ValidateTarget(t, r.Kind, solids, regions, aliases, holeNames, diagnostics);
+ continue;
+ }
+ if (r.Kind != FirmamentV2PmiKind.HoleDiameter) { diagnostics.Add($"{HoleWallConsumerInvalid}:{r.Name}"); continue; }
+ var owners = modifyBlocks.Where(block => block.SemanticHoles.Any(hole => hole.Name == holeName)).Select(block => block.TargetSolid).Distinct(StringComparer.Ordinal).ToArray();
+ if (owners.Length > 1) diagnostics.Add($"{HoleWallAmbiguous}:{holeName}");
+ else if (owners.Length == 0) diagnostics.Add($"{(solids.ContainsKey(holeName) ? HoleWallNotHole : HoleWallUnknownHole)}:{holeName}");
+ else wallTarget = new(holeName, owners[0]);
+ }
FirmamentV2LiteralValue? dim=null; FirmamentV2Tolerance? dimTol=null; FirmamentV2LiteralValue? ctlTol=null; var datumRefs=new List<string>();
if (r.Kind is FirmamentV2PmiKind.HoleDiameter or FirmamentV2PmiKind.Distance)
{
@@ -2950,7 +2968,9 @@ public static class FirmamentV2Parser
{ var d=Field(r,"datum"); if (d is null || !datums.Contains(d)) diagnostics.Add(PmiUnknownDatum); else datumRefs.Add(d); }
if (r.Kind == FirmamentV2PmiKind.HoleDiameter && Field(r,"datum") is string datum)
{ if (!datums.Contains(datum)) diagnostics.Add(PmiUnknownDatum); else datumRefs.Add(datum); }
- bound=new(r.Kind,r.Name,targets,dim,dimTol,ctlTol,datumRefs,r.SourceSpan); return !diagnostics.Any(x=>x.StartsWith("firmament-v2-pmi-",StringComparison.Ordinal) && x is not PmiUnsupported);
+ bound=new(r.Kind,r.Name,targets,dim,dimTol,ctlTol,datumRefs,r.SourceSpan, HoleWallTarget: wallTarget);
+ return !diagnostics.Any(x => (x.StartsWith("firmament-v2-pmi-", StringComparison.Ordinal) && x is not PmiUnsupported)
+ || x.StartsWith("firmament-v2-hole-wall-", StringComparison.Ordinal));
}
private static string? Field(FirmamentV2PmiRecord r,string name)=>r.Fields.TryGetValue(name,out var f)?f.Source:null;
private static FirmamentV2BoundLet? ResolveBoundLet(string s,IReadOnlyDictionary<string,FirmamentV2BoundLet> lets,IReadOnlyDictionary<string,FirmamentV2BoundLetRecord> records){var m=DottedReferenceRegex.Match(s); if(m.Success&&records.TryGetValue(m.Groups["record"].Value,out var rec)&&rec.Fields.TryGetValue(m.Groups["field"].Value,out var f))return f; return lets.TryGetValue(s,out var l)?l:null;}
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs
index 1bc70f46..f8576676 100644
--- a/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleCompositeMaterializer.cs
@@ -4,6 +4,7 @@ using Aetheris.Kernel.Core.Brep.Boolean;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Topology;
namespace Aetheris.Kernel.Firmament.Materializer;
@@ -11,7 +12,8 @@ internal sealed record AirHoleCompositeMaterializationResult(
bool Succeeded,
BrepBody? Body,
IReadOnlyList<AirHoleSimpleShaftMaterializationPlan> Plans,
- IReadOnlyList<string> Diagnostics);
+ IReadOnlyList<string> Diagnostics,
+ SemanticTopologyCorrespondence? Correspondence = null);
internal static class AirHoleCompositeMaterializer
{
@@ -70,7 +72,10 @@ internal static class AirHoleCompositeMaterializer
diagnostics.Add($"air-hole-x4 accepted semantic feature {plan.SemanticFeatureId} center=({plan.CenterU:0.###},{plan.CenterV:0.###}) radius={plan.Radius:0.###}.");
}
- var built = BrepBooleanBoxCylinderHoleBuilder.BuildComposition(composition, ToleranceContext.Default);
+ var wallFaces = new Dictionary<string, FaceId>(StringComparer.Ordinal);
+ var duplicateWallOrigin = false;
+ var built = BrepBooleanBoxCylinderHoleBuilder.BuildComposition(composition, ToleranceContext.Default,
+ (featureId, faceId) => { if (!wallFaces.TryAdd(featureId, faceId)) duplicateWallOrigin = true; });
if (!built.IsSuccess || built.Value is null)
{
diagnostics.Add("air-hole-x4 composite BRep build failed.");
@@ -78,7 +83,18 @@ internal static class AirHoleCompositeMaterializer
return new(false, null, plans, diagnostics);
}
+ if (duplicateWallOrigin || wallFaces.Count != plans.Count || plans.Any(plan => !wallFaces.ContainsKey(plan.SemanticFeatureId)))
+ {
+ diagnostics.Add("firmament-v2-hole-wall-role-unavailable: composite construction did not emit one wall role per semantic Hole.");
+ return new(false, null, plans, diagnostics);
+ }
+ var descendants = plans.Select(plan => new SemanticTopologyDescendant(
+ $"material:hole:{plan.SemanticFeatureId}:wall", "Face", SemanticTopologyRole.HoleWallFace,
+ $"hole:{plan.SemanticFeatureId}", Face: wallFaces[plan.SemanticFeatureId], ParentStableId: plan.SemanticFeatureId,
+ Addressability: SemanticTopologyAddressability.DerivedStable)).ToArray();
+ var correspondence = new SemanticTopologyCorrespondence(plans[0].SemanticFeature.TargetBodyId ?? "semantic-hole-host",
+ descendants, ["HoleAIR", "AirHoleCompositeMaterializer", "BrepBooleanBoxCylinderHoleBuilder"]);
diagnostics.Add("air-hole-x4 composite materialization succeeded through semantic AirHoleFeature plans and safe boolean AP242 BRep composition.");
- return new(true, built.Value, plans, diagnostics);
+ return new(true, built.Value, plans, diagnostics, correspondence);
}
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
index f637ba09..937a6098 100644
--- a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
@@ -238,11 +238,11 @@ internal static class AirHoleSimpleShaftMaterializer
var source = $"hole:{plan.SemanticFeatureId}";
var descendants = new SemanticTopologyDescendant[]
{
- new($"material:{source}:entry-loop", "Loop", SemanticTopologyRole.HoleEntryLoop, source, Loop: entryLoop, ParentStableId: plan.SemanticFeatureId),
- new($"material:{source}:exit-loop", "Loop", SemanticTopologyRole.HoleExitLoop, source, Loop: exitLoop, ParentStableId: plan.SemanticFeatureId),
- new($"material:{source}:entry-edge", "Edge", SemanticTopologyRole.TopBoundary, source, Edge: EdgeOf(entryLoop), ParentStableId: plan.SemanticFeatureId),
- new($"material:{source}:exit-edge", "Edge", SemanticTopologyRole.BottomBoundary, source, Edge: EdgeOf(exitLoop), ParentStableId: plan.SemanticFeatureId),
- new($"material:{source}:wall", "Face", SemanticTopologyRole.HoleWallFace, source, Face: wall.Id, ParentStableId: plan.SemanticFeatureId)
+ new($"material:{source}:entry-loop", "Loop", SemanticTopologyRole.HoleEntryLoop, source, Loop: entryLoop, ParentStableId: plan.SemanticFeatureId, Addressability: SemanticTopologyAddressability.DerivedStable),
+ new($"material:{source}:exit-loop", "Loop", SemanticTopologyRole.HoleExitLoop, source, Loop: exitLoop, ParentStableId: plan.SemanticFeatureId, Addressability: SemanticTopologyAddressability.DerivedStable),
+ new($"material:{source}:entry-edge", "Edge", SemanticTopologyRole.TopBoundary, source, Edge: EdgeOf(entryLoop), ParentStableId: plan.SemanticFeatureId, Addressability: SemanticTopologyAddressability.DerivedStable),
+ new($"material:{source}:exit-edge", "Edge", SemanticTopologyRole.BottomBoundary, source, Edge: EdgeOf(exitLoop), ParentStableId: plan.SemanticFeatureId, Addressability: SemanticTopologyAddressability.DerivedStable),
+ new($"material:{source}:wall", "Face", SemanticTopologyRole.HoleWallFace, source, Face: wall.Id, ParentStableId: plan.SemanticFeatureId, Addressability: SemanticTopologyAddressability.DerivedStable)
};
return new(plan.SemanticFeature.TargetBodyId ?? "semantic-hole-host", descendants, ["HoleAIR", "AirHoleSimpleShaftMaterializationPlan", "ThroughHoleConstructionRecipe", "BrepSurgery"]);
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/BoxConstructionCorrespondence.cs b/Aetheris.Kernel.Firmament/Materializer/BoxConstructionCorrespondence.cs
new file mode 100644
index 00000000..898b9125
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/BoxConstructionCorrespondence.cs
@@ -0,0 +1,35 @@
+using Aetheris.Kernel.Core.Brep.Features;
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+/// <summary>Maps the IDs captured by the Box extrusion itself to existing axis selectors.</summary>
+public static class BoxConstructionCorrespondence
+{
+ public static SemanticTopologyCorrespondence Create(string bodyStableId, BrepExtrudeConstructionTopology topology, FirmamentV2SourceSpan? sourceSpan = null)
+ {
+ ArgumentNullException.ThrowIfNull(topology);
+ if (topology.SideFaces.Count != 4 || topology.TopEdges.Count != 4)
+ throw new ArgumentException("A Box extrusion must have exactly four ordered sides and top edges.", nameof(topology));
+
+ // BrepPrimitives.CreateBox authors its rectangle counterclockwise from
+ // (-X,-Y), so extrusion side indices have these fixed semantic roles.
+ var faces = new[]
+ {
+ (topology.BottomFace, "-Z"), (topology.TopFace, "+Z"),
+ (topology.SideFaces[0], "-Y"), (topology.SideFaces[1], "+X"),
+ (topology.SideFaces[2], "+Y"), (topology.SideFaces[3], "-X")
+ };
+ var descendants = faces.Select(pair => new SemanticTopologyDescendant(
+ $"{bodyStableId}.face({pair.Item2})", "Face", SemanticTopologyRole.BoxFace,
+ bodyStableId, Face: pair.Item1, ParentStableId: bodyStableId,
+ FirmamentSelector: $"face({pair.Item2})",
+ Addressability: SemanticTopologyAddressability.DerivedStable)).ToList();
+ descendants.Add(new SemanticTopologyDescendant(
+ $"{bodyStableId}.edge(TopFront)", "Edge", SemanticTopologyRole.BoxEdge,
+ bodyStableId, Edge: topology.TopEdges[0], ParentStableId: bodyStableId,
+ Addressability: SemanticTopologyAddressability.DerivedStable));
+ return new(bodyStableId, descendants, ["FirmamentBox", "BrepPrimitives.CreateBox", "BrepExtrudeConstructionTopology"],
+ sourceSpan is null ? null : new Dictionary<string, FirmamentV2SourceSpan> { [bodyStableId] = sourceSpan });
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/GeometrySourceMap.cs b/Aetheris.Kernel.Firmament/Materializer/GeometrySourceMap.cs
new file mode 100644
index 00000000..b02a6937
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/GeometrySourceMap.cs
@@ -0,0 +1,41 @@
+using Aetheris.Kernel.Core.Topology;
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+/// <summary>Build-local index of the construction correspondence, never a geometry recognizer.</summary>
+public sealed class GeometrySourceMap
+{
+ private readonly Dictionary<FaceId, SemanticTopologyDescendant> _faces = new();
+ private readonly Dictionary<EdgeId, SemanticTopologyDescendant> _edges = new();
+ private readonly Dictionary<string, IReadOnlyList<SemanticTopologyDescendant>> _semanticKeys;
+ private readonly Dictionary<string, IReadOnlyList<SemanticTopologyDescendant>> _sourceSymbols;
+ private readonly IReadOnlyDictionary<string, FirmamentV2SourceSpan> _sourceSpans;
+
+ public GeometrySourceMap(SemanticTopologyCorrespondence correspondence)
+ {
+ ArgumentNullException.ThrowIfNull(correspondence);
+ foreach (var descendant in correspondence.Descendants)
+ {
+ if (descendant.Face is { } face && !_faces.TryAdd(face, descendant))
+ throw new InvalidOperationException($"Duplicate construction correspondence for BRep face {face.Value}.");
+ if (descendant.Edge is { } edge && !_edges.TryAdd(edge, descendant))
+ throw new InvalidOperationException($"Duplicate construction correspondence for BRep edge {edge.Value}.");
+ }
+ var semanticGroups = correspondence.Descendants.GroupBy(item => item.StableId, StringComparer.Ordinal).ToArray();
+ foreach (var group in semanticGroups)
+ if (group.Select(item => (item.Role, item.SourceStableId, item.ParentStableId)).Distinct().Skip(1).Any())
+ throw new InvalidOperationException($"Conflicting construction origins for semantic key '{group.Key}'.");
+ _semanticKeys = semanticGroups
+ .ToDictionary(group => group.Key, group => (IReadOnlyList<SemanticTopologyDescendant>)group.ToArray(), StringComparer.Ordinal);
+ _sourceSymbols = correspondence.Descendants.GroupBy(item => item.ParentStableId ?? item.SourceStableId, StringComparer.Ordinal)
+ .ToDictionary(group => group.Key, group => (IReadOnlyList<SemanticTopologyDescendant>)group.ToArray(), StringComparer.Ordinal);
+ _sourceSpans = correspondence.SourceSpans ?? new Dictionary<string, FirmamentV2SourceSpan>();
+ }
+
+ public bool TryGetByBrepFace(FaceId face, out SemanticTopologyDescendant descendant) => _faces.TryGetValue(face, out descendant!);
+ public bool TryGetByBrepEdge(EdgeId edge, out SemanticTopologyDescendant descendant) => _edges.TryGetValue(edge, out descendant!);
+ public IReadOnlyList<SemanticTopologyDescendant> GetEntitiesForSemanticKey(string key) => _semanticKeys.GetValueOrDefault(key) ?? [];
+ public IReadOnlyList<SemanticTopologyDescendant> GetEntitiesForSourceSymbol(string symbol) => _sourceSymbols.GetValueOrDefault(symbol) ?? [];
+ public bool TryGetSourceSpan(string symbol, out FirmamentV2SourceSpan span) => _sourceSpans.TryGetValue(symbol, out span!);
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
index e6d4ae83..5459141c 100644
--- a/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/SemanticTopologySelections.cs
@@ -7,7 +7,8 @@ using Aetheris.Semantics;
namespace Aetheris.Kernel.Firmament.Materializer;
/// <summary>Stable roles assigned while an authoritative plan is materialized. These are not geometric queries.</summary>
-public enum SemanticTopologyRole { Unknown, ProfileVertex, VerticalExtrusionEdge, LocalStartBoundary, LocalEndBoundary, LocalStartCapLoop, LocalEndCapLoop, TopBoundary, BottomBoundary, ExtrusionSideFace, TopFaceBoundaryLoop, BottomFaceBoundaryLoop, HoleEntryLoop, HoleExitLoop, HoleWallFace, HoleShaftToDrillPointLoop, HoleShaftToDrillPointEdge, HoleDrillPointFace, HoleTipVertex, HoleCounterboreMouthLoop, HoleCounterboreWallFace, HoleCounterboreShoulderLoop, HoleCounterboreShaftWallFace, SlotEntryLoop, SlotExitLoop, SlotWallFace, SlotStraightWallFace, SlotEndWallFace, ComposeTransition, EdgeFinishReplacementFace, FilletSurface, ConvexJunctionPatch, ReflexJunctionPatch, CapContactEdge, SideContactEdge, JunctionToRollA, JunctionToRollB, JunctionCapContact, JunctionSideAContact, JunctionSideBContact, StartTerminationFace, EndTerminationFace, StartEndpointArc, EndEndpointArc, RetainedStartSharpEdge, RetainedEndSharpEdge }
+public enum SemanticTopologyRole { Unknown, ProfileVertex, VerticalExtrusionEdge, LocalStartBoundary, LocalEndBoundary, LocalStartCapLoop, LocalEndCapLoop, TopBoundary, BottomBoundary, ExtrusionSideFace, TopFaceBoundaryLoop, BottomFaceBoundaryLoop, HoleEntryLoop, HoleExitLoop, HoleWallFace, HoleShaftToDrillPointLoop, HoleShaftToDrillPointEdge, HoleDrillPointFace, HoleTipVertex, HoleCounterboreMouthLoop, HoleCounterboreWallFace, HoleCounterboreShoulderLoop, HoleCounterboreShaftWallFace, SlotEntryLoop, SlotExitLoop, SlotWallFace, SlotStraightWallFace, SlotEndWallFace, ComposeTransition, EdgeFinishReplacementFace, FilletSurface, ConvexJunctionPatch, ReflexJunctionPatch, CapContactEdge, SideContactEdge, JunctionToRollA, JunctionToRollB, JunctionCapContact, JunctionSideAContact, JunctionSideBContact, StartTerminationFace, EndTerminationFace, StartEndpointArc, EndEndpointArc, RetainedStartSharpEdge, RetainedEndSharpEdge, BoxFace, BoxEdge }
+public enum SemanticTopologyAddressability { AuthoredStable, DerivedStable, ImportedStable, RuntimeOnly, Ambiguous, Unstable }
public enum SemanticSelectionRequirement { ExactlyOne, OneOrMore, ConnectedChain, ClosedLoop, NonEmptyFaceSet }
public enum SemanticSelectionFailure { None, SemanticSourceNotFound, NoMaterializedDescendants, AmbiguousBodyContext, SelectionCardinalityMismatch, DescendantsNotConnected, DescendantsBranch, DescendantsDoNotClose, MixedBoundaryRoles, UnsupportedTopologyChange, SelectionConsumerMismatch }
@@ -15,12 +16,15 @@ public enum SemanticSelectionFailure { None, SemanticSourceNotFound, NoMateriali
public sealed record SemanticTopologyDescendant(
string StableId, string Kind, SemanticTopologyRole Role, string SourceStableId,
EdgeId? Edge = null, FaceId? Face = null, LoopId? Loop = null, VertexId? Vertex = null,
- string? ParentStableId = null, string? GeometryPreview = null);
+ string? ParentStableId = null, string? GeometryPreview = null,
+ string? FirmamentSelector = null,
+ SemanticTopologyAddressability Addressability = SemanticTopologyAddressability.RuntimeOnly);
public sealed record SemanticTopologyCorrespondence(
string BodyStableId,
IReadOnlyList<SemanticTopologyDescendant> Descendants,
- IReadOnlyList<string> ProvenanceChain)
+ IReadOnlyList<string> ProvenanceChain,
+ IReadOnlyDictionary<string, FirmamentV2SourceSpan>? SourceSpans = null)
{
public IReadOnlyList<SemanticTopologyDescendant> FromSources(IEnumerable<string> sources, SemanticTopologyRole? role) =>
Descendants.Where(x => sources.Contains(x.SourceStableId, StringComparer.Ordinal) && (role is null || x.Role == role)).ToArray();
diff --git a/Aetheris.Kernel.Firmament/Materializer/WireForm.cs b/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
index cc8d0a52..2b7f9c37 100644
--- a/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
@@ -63,7 +63,7 @@ public sealed record WireAxisCoilAir(string Name, int Ordinal, double RadiusMm,
: WireCoilAir(Name, Ordinal, Turns, Handedness, StartPhaseRadians, Input, Output, LengthMm,
MinimumSelfClearanceMm, ApproximationToleranceMm)
{
- public override string CoilKind => "AxisCoil";
+ public override string CoilKind => "Helix";
public override string ProgressionLaw => "AxialPitch";
public override Point3D Evaluate(double t) => WireCoilGeometry.EvaluateAxis(this, t);
public override Direction3D Tangent(double t) => WireCoilGeometry.TangentAxis(this, t);
@@ -106,7 +106,7 @@ public static class WireFormAuthoring
{
public const string FrameTransportPolicy = "The authored local Up/Right bend-plane axis is rotated with the tangent through each bend (rotation-minimal rigid transport about the bend normal); Straight preserves the frame.";
private static readonly Regex Declaration = new(@"\bWireForm\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
- private static readonly Regex Operation = new(@"\b(?<kind>Straight|Bend|AxisCoil|SurfaceCoil|Coil|Knot)\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex Operation = new(@"\b(?<kind>Straight|Bend|Helix|AxisCoil|SurfaceCoil|Coil|Knot)\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
public static bool IsWireFormSource(string source) => Declaration.IsMatch(source);
@@ -158,7 +158,7 @@ public static class WireFormAuthoring
continue;
}
- if (match.Groups["kind"].Value is "AxisCoil" or "Coil")
+ if (match.Groups["kind"].Value is "Helix" or "AxisCoil" or "Coil")
{
var coil = WireCoilAuthoring.CreateAxis(operationName, ordinal, operationBody, state, diameter);
if (!coil.IsSuccess) return KernelResult<WireFormFeatureAir>.Failure(coil.Diagnostics);
@@ -201,7 +201,7 @@ public static class WireFormAuthoring
operations.Add(new WireBendAir(operationName, ordinal, radius, angle, plane, axis, center, startRadial, state, bendOutput));
state = bendOutput;
}
- if (operations.Count == 0) return Fail("wireform-operations-empty", $"WireForm '{name}' requires at least one Straight, Bend, AxisCoil, SurfaceCoil, or Knot operation.");
+ if (operations.Count == 0) return Fail("wireform-operations-empty", $"WireForm '{name}' requires at least one Straight, Bend, Helix, SurfaceCoil, or Knot operation.");
var authoredStart = new WireState(new(origin.X, origin.Y, origin.Z), tangent, up, 0d);
return KernelResult<WireFormFeatureAir>.Success(new(name, diameter, materialReference, material.Material,
operations[0] is WireKnotPathAir ? operations[0].Input : authoredStart, operations,
@@ -442,7 +442,7 @@ public static class WireFormReportFactory
var feature = built.Feature;
var surfaces = built.Body.Topology.Faces.Select(face => built.Body.GetFaceSurface(face.Id).Kind).ToArray();
var operations = feature.Operations.Select(operation => new FirmamentWireOperationReport(
- operation.Ordinal, operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "AxisCoil", WireSurfaceCoilAir => "SurfaceCoil", WireKnotPathAir => "KnotPath", _ => "Unknown" }, operation.LengthMm,
+ operation.Ordinal, operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "Helix", WireSurfaceCoilAir => "SurfaceCoil", WireKnotPathAir => "KnotPath", _ => "Unknown" }, operation.LengthMm,
operation is WireBendAir bend ? bend.RadiusMm : null,
operation is WireBendAir bendAngle ? bendAngle.AngleRadians * 180d / Math.PI : null,
operation is WireBendAir bendPlane ? bendPlane.Plane : null, operation.StableId(feature.Name),
diff --git a/Aetheris.Kernel.StandardLibrary/Materials/MaterialCatalog.cs b/Aetheris.Kernel.StandardLibrary/Materials/MaterialCatalog.cs
index 59c1d0e5..59d0e6bb 100644
--- a/Aetheris.Kernel.StandardLibrary/Materials/MaterialCatalog.cs
+++ b/Aetheris.Kernel.StandardLibrary/Materials/MaterialCatalog.cs
@@ -84,6 +84,13 @@ public sealed class MaterialCatalog : IDisposable
structural,
new(values.GetValueOrDefault(MaterialPropertyKind.ThermalConductivity), values.GetValueOrDefault(MaterialPropertyKind.SpecificHeat), values.GetValueOrDefault(MaterialPropertyKind.CoefficientOfThermalExpansion)), values);
}
+
+ // Browser WebAssembly cannot initialize the EF/SQLite compiled model. Use
+ // the very same immutable rows that seed the desktop catalog, with the
+ // same identity filter, validation, and ResolvedMaterial mapping.
+ internal static IReadOnlyList<ResolvedMaterial> FindBundledByReference(string reference) => MaterialSeedData.Create()
+ .Where(x => x.FirmamentPath == reference || x.StableId == reference || (x.CatalogId + ":" + x.StableId) == reference)
+ .OrderBy(x => x.StableId).Select(Map).ToArray();
}
public sealed class MaterialResolver(Func<MaterialCatalog> catalogFactory) : IMaterialResolver
@@ -95,8 +102,10 @@ public sealed class MaterialResolver(Func<MaterialCatalog> catalogFactory) : IMa
if (string.IsNullOrWhiteSpace(reference)) return MaterialResolutionResult.Failure(MaterialResolutionError.UnknownMaterial, "Material reference is empty.");
try
{
- using var catalog = catalogFactory();
- var matches = catalog.FindByReference(reference.Trim());
+ var normalized = reference.Trim();
+ IReadOnlyList<ResolvedMaterial> matches;
+ if (OperatingSystem.IsBrowser()) matches = MaterialCatalog.FindBundledByReference(normalized);
+ else { using var catalog = catalogFactory(); matches = catalog.FindByReference(normalized); }
return matches.Count switch
{
0 => MaterialResolutionResult.Failure(MaterialResolutionError.UnknownMaterial, $"Unknown material reference '{reference}'. Use a stable catalog ID or Firmament material path."),
diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.cs
index b589ee13..ecaa955d 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -206,16 +206,33 @@ public static partial class Program
if (!build.IsSuccess || build.Value is null)
return WebBuildResult.Failed(Diagnostics(build.Diagnostics, _sourceName), compileMs);
var step = build.Value.StepText;
- var import = Step242Importer.ImportBody(step);
- if (!import.IsSuccess || import.Value is null)
- return WebBuildResult.Failed(Diagnostics(import.Diagnostics, _sourceName), compileMs);
+ BrepBody displayBody;
+ if (build.Value.RuntimeBody is { } canonicalBody) displayBody = canonicalBody;
+ else
+ {
+ var import = Step242Importer.ImportBody(step);
+ if (!import.IsSuccess || import.Value is null)
+ return WebBuildResult.Failed(Diagnostics(import.Diagnostics, _sourceName), compileMs);
+ displayBody = import.Value;
+ }
watch.Restart();
var definitionId = "definition:" + Sha(step)[..16].ToLowerInvariant();
- var entityId = string.IsNullOrWhiteSpace(build.Value.ExportedFeatureId) ? Id + ":body" : build.Value.ExportedFeatureId;
- var mesh = WebMeshBuilder.Build(Name, definitionId, entityId, import.Value);
+ var entityId = build.Value.RuntimeCorrespondence?.BodyStableId
+ ?? (string.IsNullOrWhiteSpace(build.Value.ExportedFeatureId) ? Id + ":body" : build.Value.ExportedFeatureId);
+ var sourceMap = build.Value.RuntimeCorrespondence is { } correspondence
+ ? new Aetheris.Kernel.Firmament.Materializer.GeometrySourceMap(correspondence) : null;
+ WebSourceRef? CompilerSource(string symbol) =>
+ sourceMap?.TryGetSourceSpan(symbol, out var span) == true
+ ? SourceRefAt(_sourceName, effective, span.Start, span.Length) : null;
+ var boxSource = CompilerSource(entityId);
+ var featureSources = (build.Value.Features ?? []).ToDictionary(feature => feature.FeatureId,
+ feature => CompilerSource(feature.FeatureId), StringComparer.Ordinal);
+ var mesh = WebMeshBuilder.Build(Name, definitionId, entityId, displayBody,
+ build.Value.RuntimeCorrespondence, boxSource, Revision + 1, featureSources);
var meshMs = watch.Elapsed.TotalMilliseconds;
- var featureNodes = (build.Value.EngineeringFeatures ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true, null)).ToArray();
- var body = new WebTreeNode(entityId, build.Value.ExportedBodyCategory, Name, Id, featureNodes.Select(item => item.Id).ToArray(), true, SourceRef(_sourceName, 0, effective.Length));
+ var featureNodes = (build.Value.EngineeringFeatures ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true, null))
+ .Concat((build.Value.Features ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true, featureSources[feature.FeatureId], feature.Diameter))).ToArray();
+ var body = new WebTreeNode(entityId, build.Value.ExportedBodyCategory, Name, Id, featureNodes.Select(item => item.Id).ToArray(), true, boxSource ?? SourceRef(_sourceName, 0, effective.Length));
var root = new WebTreeNode(Id, "Model", Name, null, [body.Id], true, SourceRef(_sourceName, 0, effective.Length));
var tree = new { rootId = root.Id, nodes = new[] { root, body }.Concat(featureNodes).ToArray() };
return WebBuildResult.Passed(step, tree, mesh, [Id, entityId, .. featureNodes.Select(item => item.Id)], compileMs, meshMs);
@@ -260,6 +277,13 @@ public static partial class Program
diagnostic.Code.ToString(), diagnostic.Message, SourceRef(source, 0, 0), diagnostic.Source)).ToArray();
private static WebSourceRef SourceRef(string source, int start, int length) => new(source, 1, 1, start, length);
+ private static WebSourceRef SourceRefAt(string name, string text, int start, int length)
+ {
+ var prefix = text[..start];
+ var line = 1 + prefix.Count(character => character == '\n');
+ var lastBreak = prefix.LastIndexOf('\n');
+ return new(name, line, start - lastBreak, start, length);
+ }
private static string Sha(string value) => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(value)));
}
@@ -328,27 +352,52 @@ internal static class ParameterInspector
internal static class WebMeshBuilder
{
- public static object Build(string name, string definitionId, string entityId, BrepBody body)
+ public static object Build(string name, string definitionId, string entityId, BrepBody body,
+ Aetheris.Kernel.Firmament.Materializer.SemanticTopologyCorrespondence? correspondence = null,
+ WebSourceRef? source = null, int buildRevision = 0, IReadOnlyDictionary<string, WebSourceRef?>? featureSources = null)
{
// Browser WASM has no blocking monitor wait. Use the existing synchronous
// tessellator authority; the Worker transport supplies UI responsiveness.
var tessellation = BrepDisplayTessellator.Tessellate(body, new DisplayTessellationOptions(double.Pi / 16, .3, 6, 64));
if (!tessellation.IsSuccess) throw new InvalidOperationException(string.Join("; ", tessellation.Diagnostics.Select(item => item.Message)));
var positions = new List<double>(); var normals = new List<double>(); var indices = new List<int>(); var ranges = new List<object>();
+ var sourceMap = correspondence is null ? null : new Aetheris.Kernel.Firmament.Materializer.GeometrySourceMap(correspondence);
foreach (var face in tessellation.Value.FacePatches.OrderBy(face => face.FaceId.Value))
{
var vertexOffset = positions.Count / 3; var triangleStart = indices.Count / 3;
positions.AddRange(face.Positions.SelectMany(point => new[] { point.X, point.Y, point.Z }));
normals.AddRange(face.Normals.SelectMany(normal => new[] { normal.X, normal.Y, normal.Z }));
indices.AddRange(face.TriangleIndices.Select(index => index + vertexOffset));
- ranges.Add(new { startTriangle = triangleStart, triangleCount = face.TriangleIndices.Count / 3, faceId = $"face:{face.FaceId.Value}", semanticEntityId = entityId });
+ Aetheris.Kernel.Firmament.Materializer.SemanticTopologyDescendant? semanticFace = null;
+ if (sourceMap is not null && sourceMap.TryGetByBrepFace(face.FaceId, out var mappedFace)) semanticFace = mappedFace;
+ var owner = semanticFace?.ParentStableId is { } parent && featureSources?.ContainsKey(parent) == true ? parent : entityId;
+ var faceSource = owner == entityId ? source : featureSources![owner];
+ ranges.Add(new { startTriangle = triangleStart, triangleCount = face.TriangleIndices.Count / 3, faceId = $"face:{face.FaceId.Value}", semanticEntityId = owner,
+ semanticTopologyId = semanticFace?.StableId, topologyKind = "Face", outputRole = semanticFace?.Role.ToString(), originFeature = semanticFace?.SourceStableId,
+ sourceAddressability = semanticFace?.Addressability.ToString() ?? "RuntimeOnly",
+ selector = semanticFace?.FirmamentSelector,
+ selectorReason = semanticFace is null ? "No compiler-owned source topology mapping is available for this display face."
+ : semanticFace.FirmamentSelector is null ? "Construction identity is known, but Firmament has no qualified source selector for this topology." : null,
+ source = semanticFace is null ? null : faceSource, buildRevision });
}
return new
{
schema = "aetheris/display-mesh/1",
name,
units = "mm",
- definitions = new[] { new { id = definitionId, identity = entityId, positions = positions.ToArray(), normals = normals.ToArray(), indices = indices.ToArray(), ranges } },
+ definitions = new[] { new { id = definitionId, identity = entityId, positions = positions.ToArray(), normals = normals.ToArray(), indices = indices.ToArray(), ranges,
+ edges = tessellation.Value.EdgePolylines.Select(edge =>
+ {
+ Aetheris.Kernel.Firmament.Materializer.SemanticTopologyDescendant? semanticEdge = null;
+ if (sourceMap is not null && sourceMap.TryGetByBrepEdge(edge.EdgeId, out var mappedEdge)) semanticEdge = mappedEdge;
+ var owner = semanticEdge?.ParentStableId is { } parent && featureSources?.ContainsKey(parent) == true ? parent : entityId;
+ return new { edgeId = $"edge:{edge.EdgeId.Value}", points = edge.Points.Select(point => new[] { point.X, point.Y, point.Z }).ToArray(), closed = edge.IsClosed,
+ semanticEntityId = owner, semanticTopologyId = semanticEdge?.StableId, topologyKind = "Edge", outputRole = semanticEdge?.Role.ToString(), originFeature = semanticEdge?.SourceStableId,
+ sourceAddressability = semanticEdge?.Addressability.ToString() ?? "RuntimeOnly", selector = semanticEdge?.FirmamentSelector,
+ selectorReason = semanticEdge is null ? "Display BRep edge has no construction-owned source correspondence."
+ : semanticEdge.FirmamentSelector is null ? "Construction identity is known, but Firmament has no qualified source selector for this edge." : null,
+ source = semanticEdge is null ? null : owner == entityId ? source : featureSources![owner], buildRevision };
+ }).ToArray() } },
occurrences = new[] { new { id = entityId + ":occurrence", path = name, parentId = (string?)null, definitionId, semanticEntityId = entityId, transform = new double[] { 1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1 } } }
};
}
@@ -357,7 +406,7 @@ internal static class WebMeshBuilder
internal sealed record WebPropertyValue(double Value, string Unit);
internal sealed record WebSourceRef(string Source, int Line, int Column, int Start, int Length);
internal sealed record WebProperty(string Id, string OwnerEntityId, string Name, string Type, string Unit, double Value, bool Writable, int Start, int Length, WebSourceRef Source);
-internal sealed record WebTreeNode(string Id, string Kind, string Name, string? ParentId, IReadOnlyList<string> Children, bool Visible, WebSourceRef? Source);
+internal sealed record WebTreeNode(string Id, string Kind, string Name, string? ParentId, IReadOnlyList<string> Children, bool Visible, WebSourceRef? Source, double? HoleDiameterMm = null);
internal sealed record WebDiagnostic(string Severity, string Code, string Message, WebSourceRef? Source = null, string? Details = null);
internal sealed record WebBuildResult(bool Success, int Revision, object? Model, IReadOnlyList<WebDiagnostic> Diagnostics, bool RetainedPreviousGeometry,
object? Tree = null, object? Mesh = null, IReadOnlyList<string>? EntityIds = null, object? Timings = null, object? Changes = null, string? StepText = null)
diff --git a/Aetheris.Web.Runtime/sdk/README.md b/Aetheris.Web.Runtime/sdk/README.md
index 4937e67c..fdab71cd 100644
--- a/Aetheris.Web.Runtime/sdk/README.md
+++ b/Aetheris.Web.Runtime/sdk/README.md
@@ -10,6 +10,14 @@ const { model, diagnostics } = await cad.compile(source, { sourceName: 'bracket.
Vite projects add `aetherisCad()` from `@aetheris/cad/vite` to `vite.config.js`. The plugin serves the runtime during development and copies it into production builds.
+## Selection correspondence
+
+`model.describeSelection(definitionId, triangleIndex, occurrenceId)` returns the picked face's runtime ID, semantic topology ID when known, source addressability, canonical selector when admitted, source range, and build revision. `model.selectionForSemanticId(id)` and `model.selectionForSourceSymbol(symbol)` find display ranges in the current model. Use these ranges only with the current model revision.
+
+Geometry provenance is assigned during Firmament parsing and BRep construction, then copied to display patches. The browser does not identify source features from face shape, tessellation indices, or STEP entity numbers. `model.describeEdgeSelection(...)` reads the same construction metadata for true BRep edges; `model.geometrySourceMap()` dumps the current face and edge records for inspection. A source range can be available even when Firmament has no qualified selector for that topology.
+
+For a single, unmodified Firmament `Box`, the Web runtime tessellates the canonical BRep directly. Construction-owned face IDs map its six faces to `face(±X)`, `face(±Y)`, and `face(±Z)`. A single simple through-hole also retains its construction-owned wall and rim identity through direct display, but the wall and rim have no qualified Firmament selector yet. Display definitions include BRep edge polylines for a truthful edge overlay; these are not source selectors. The STEP export remains available. Other routes that reimport STEP currently return `RuntimeOnly` display faces with no source selector. A display `faceId` or triangle index is never itself a Firmament selector.
+
X1 runs on the page thread. `worker: true` fails with the typed `worker-unavailable` error; a qualified Worker transport is deferred rather than silently changing behavior.
The preview package is AGPL-3.0-only. Contact the Aetheris project for commercial licensing; this statement is package metadata, not legal advice.
diff --git a/Aetheris.Web.Runtime/sdk/src/index.d.ts b/Aetheris.Web.Runtime/sdk/src/index.d.ts
index 9255de02..b6975dcf 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.d.ts
+++ b/Aetheris.Web.Runtime/sdk/src/index.d.ts
@@ -4,10 +4,13 @@ export interface SourceReference { readonly source: string; readonly line: numbe
export interface Diagnostic { readonly severity: DiagnosticSeverity; readonly code: string; readonly message: string; readonly source?: SourceReference; readonly details?: string }
export interface UnitValue { readonly value: number; readonly unit: Unit }
export interface EditableProperty { readonly id: string; readonly ownerEntityId: string; readonly name: string; readonly type: 'Length' | 'Angle' | 'Integer' | 'Number' | 'Boolean' | 'Enum'; readonly unit: Unit; readonly value: number; readonly writable: boolean; readonly source: SourceReference }
-export interface ModelTreeNode { readonly id: string; readonly kind: string; readonly name: string; readonly parentId?: string; readonly children: readonly string[]; readonly visible: boolean; readonly source?: SourceReference }
+export interface ModelTreeNode { readonly id: string; readonly kind: string; readonly name: string; readonly parentId?: string; readonly children: readonly string[]; readonly visible: boolean; readonly source?: SourceReference; readonly holeDiameterMm?: number | null }
export interface ModelTree { readonly rootId: string; readonly nodes: readonly ModelTreeNode[] }
-export interface MeshRange { readonly startTriangle: number; readonly triangleCount: number; readonly faceId: string; readonly semanticEntityId: string }
-export interface DisplayMeshDefinition { readonly id: string; readonly identity: string; readonly positions: Float64Array; readonly normals: Float64Array; readonly indices: Uint32Array; readonly ranges: readonly MeshRange[] }
+export type SourceAddressability = 'AuthoredStable' | 'DerivedStable' | 'ImportedStable' | 'RuntimeOnly' | 'Ambiguous' | 'Unstable';
+export interface MeshRange { readonly startTriangle: number; readonly triangleCount: number; readonly faceId: string; readonly semanticEntityId: string; readonly semanticTopologyId?: string | null; readonly topologyKind?: 'Face'; readonly outputRole?: string | null; readonly originFeature?: string | null; readonly sourceAddressability?: SourceAddressability; readonly selector?: string | null; readonly selectorReason?: string | null; readonly source?: SourceReference | null; readonly buildRevision?: number }
+export interface SelectionDescription { readonly semanticEntityId: string; readonly faceId: string; readonly occurrenceId: string; readonly definitionId: string; readonly semanticTopologyId: string | null; readonly topologyKind: string; readonly outputRole: string | null; readonly originFeature: string | null; readonly selector: string | null; readonly sourceAddressability: SourceAddressability; readonly selectorReason: string | null; readonly source: SourceReference | null; readonly buildRevision: number; readonly sourceAddressable: boolean }
+export interface DisplayEdgePolyline { readonly edgeId: string; readonly points: readonly (readonly number[])[]; readonly closed: boolean; readonly semanticEntityId?: string; readonly semanticTopologyId?: string | null; readonly topologyKind?: 'Edge'; readonly outputRole?: string | null; readonly originFeature?: string | null; readonly sourceAddressability?: SourceAddressability; readonly selector?: string | null; readonly selectorReason?: string | null; readonly source?: SourceReference | null; readonly buildRevision?: number }
+export interface DisplayMeshDefinition { readonly id: string; readonly identity: string; readonly positions: Float64Array; readonly normals: Float64Array; readonly indices: Uint32Array; readonly ranges: readonly MeshRange[]; readonly edges?: readonly DisplayEdgePolyline[] }
export interface DisplayMeshOccurrence { readonly id: string; readonly path: string; readonly parentId?: string; readonly definitionId?: string; readonly semanticEntityId: string; readonly transform: readonly number[] }
export interface DisplayMesh { readonly schema: 'aetheris/display-mesh/1' | 'aetheris/assembly-display-mesh/1'; readonly name: string; readonly units: 'mm'; readonly definitions: readonly DisplayMeshDefinition[]; readonly occurrences: readonly DisplayMeshOccurrence[] }
export interface ChangeSet { readonly changedEntityIds: readonly string[]; readonly addedEntityIds: readonly string[]; readonly removedEntityIds: readonly string[]; readonly meshChanged: boolean; readonly diagnosticsChanged: boolean }
@@ -34,8 +37,13 @@ export class ModelSession {
setProperty(propertyId: string, value: UnitValue, options?: OperationOptions): Promise<RebuildResult>;
setSource(source: string, options?: CompileOptions): Promise<RebuildResult>;
rebuild(options?: OperationOptions): Promise<RebuildResult>;
- resolveSelection(definitionId: string, triangleIndex: number, occurrenceId?: string): { semanticEntityId: string; faceId: string; occurrenceId: string; definitionId: string } | null;
+ resolveSelection(definitionId: string, triangleIndex: number, occurrenceId?: string): Omit<SelectionDescription, 'sourceAddressable'> | null;
+ describeSelection(definitionId: string, triangleIndex: number, occurrenceId?: string): SelectionDescription | null;
+ describeEdgeSelection(definitionId: string, edgeId: string, occurrenceId?: string): SelectionDescription | null;
+ selectionForSemanticId(semanticTopologyId: string): readonly ({ definitionId: string } & MeshRange)[];
+ selectionForSourceSymbol(symbol: string): readonly ({ definitionId: string } & MeshRange)[];
selectionForEntity(entityId: string): { occurrenceIds: readonly string[]; ranges: readonly ({ definitionId: string } & MeshRange)[] };
+ geometrySourceMap(): readonly { definitionId: string; topologyId: string; topologyKind: string; semanticKey: string | null; outputRole: string | null; originFeature: string | null; source: SourceReference | null; selector: string | null; qualification: SourceAddressability; buildRevision: number }[];
exportSTEP(options?: OperationOptions): Promise<Uint8Array>;
exportSTEPBlob(options?: OperationOptions): Promise<Blob>;
dispose(): Promise<void>;
diff --git a/Aetheris.Web.Runtime/sdk/src/index.js b/Aetheris.Web.Runtime/sdk/src/index.js
index 72149ab6..f6e3386e 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.js
+++ b/Aetheris.Web.Runtime/sdk/src/index.js
@@ -67,7 +67,30 @@ export class Aetheris {
export class ModelSession {
constructor(transport, snapshot) { this.transport = transport; this.apply(snapshot); this.queue = Promise.resolve(); }
- apply(snapshot) { Object.assign(this, snapshot); }
+ apply(snapshot) {
+ Object.assign(this, snapshot);
+ this._rangesBySemantic = new Map();
+ this._rangesBySource = new Map();
+ this._rangesByEntity = new Map();
+ this._rangesByDefinition = new Map();
+ this._geometrySourceMap = [];
+ const add = (index, key, value) => { if (key != null) { const items = index.get(key) ?? []; items.push(value); index.set(key, items); } };
+ for (const definition of this.mesh.definitions) {
+ for (const range of definition.ranges ?? []) {
+ const item = { definitionId: definition.id, ...range };
+ add(this._rangesBySemantic, range.semanticTopologyId, item);
+ add(this._rangesBySource, range.originFeature, item);
+ add(this._rangesByEntity, range.semanticEntityId, item);
+ add(this._rangesByDefinition, definition.id, item);
+ this._geometrySourceMap.push({ definitionId: definition.id, topologyId: range.faceId, topologyKind: 'Face', semanticKey: range.semanticTopologyId ?? null,
+ outputRole: range.outputRole ?? null, originFeature: range.originFeature ?? null, source: range.source ?? null,
+ selector: range.selector ?? null, qualification: range.sourceAddressability ?? 'RuntimeOnly', buildRevision: range.buildRevision ?? this.revision });
+ }
+ for (const edge of definition.edges ?? []) this._geometrySourceMap.push({ definitionId: definition.id, topologyId: edge.edgeId, topologyKind: 'Edge',
+ semanticKey: edge.semanticTopologyId ?? null, outputRole: edge.outputRole ?? null, originFeature: edge.originFeature ?? null,
+ source: edge.source ?? null, selector: edge.selector ?? null, qualification: edge.sourceAddressability ?? 'RuntimeOnly', buildRevision: edge.buildRevision ?? this.revision });
+ }
+ }
entity(id) { return this.tree.nodes.find(node => node.id === id); }
property(id) { return this.properties.find(property => property.id === id); }
async setProperty(propertyId, value, options = {}) {
@@ -86,15 +109,44 @@ export class ModelSession {
const definition = this.mesh.definitions.find(item => item.id === definitionId);
const occurrence = occurrenceId ? this.mesh.occurrences.find(item => item.id === occurrenceId) : this.mesh.occurrences.find(item => item.definitionId === definitionId);
const range = definition?.ranges?.find(item => triangleIndex >= item.startTriangle && triangleIndex < item.startTriangle + item.triangleCount);
- return range && occurrence ? { semanticEntityId: occurrence.semanticEntityId ?? range.semanticEntityId, faceId: range.faceId, occurrenceId: occurrence.id, definitionId } : null;
+ return range && occurrence ? { semanticEntityId: range.semanticEntityId ?? occurrence.semanticEntityId, faceId: range.faceId, occurrenceId: occurrence.id, definitionId,
+ semanticTopologyId: range.semanticTopologyId ?? null, topologyKind: range.topologyKind ?? 'Face', outputRole: range.outputRole ?? null, originFeature: range.originFeature ?? null,
+ selector: range.selector ?? null, sourceAddressability: range.sourceAddressability ?? 'RuntimeOnly',
+ selectorReason: range.selectorReason ?? null, source: range.source ?? null, buildRevision: range.buildRevision ?? this.revision } : null;
+ }
+ describeSelection(definitionId, triangleIndex, occurrenceId) {
+ const selection = this.resolveSelection(definitionId, triangleIndex, occurrenceId);
+ if (!selection) return null;
+ return { ...selection, sourceAddressable: selection.source != null && ['AuthoredStable', 'DerivedStable'].includes(selection.sourceAddressability),
+ selectorReason: selection.selectorReason ?? (selection.selector ? null : 'No compiler-owned source selector mapping is available for this display face.') };
+ }
+ describeEdgeSelection(definitionId, edgeId, occurrenceId) {
+ const definition = this.mesh.definitions.find(item => item.id === definitionId);
+ const occurrence = occurrenceId ? this.mesh.occurrences.find(item => item.id === occurrenceId) : this.mesh.occurrences.find(item => item.definitionId === definitionId);
+ const edge = definition?.edges?.find(item => item.edgeId === edgeId);
+ if (!edge || !occurrence) return null;
+ return { semanticEntityId: edge.semanticEntityId ?? occurrence.semanticEntityId, faceId: edge.edgeId, occurrenceId: occurrence.id, definitionId,
+ semanticTopologyId: edge.semanticTopologyId ?? null, topologyKind: 'Edge', outputRole: edge.outputRole ?? null, originFeature: edge.originFeature ?? null,
+ selector: edge.selector ?? null, sourceAddressability: edge.sourceAddressability ?? 'RuntimeOnly',
+ selectorReason: edge.selectorReason ?? 'This edge has no qualified Firmament source selector.',
+ source: edge.source ?? null, buildRevision: edge.buildRevision ?? this.revision,
+ sourceAddressable: edge.source != null && ['AuthoredStable', 'DerivedStable'].includes(edge.sourceAddressability) };
+ }
+ selectionForSemanticId(semanticTopologyId) {
+ return this._rangesBySemantic.get(semanticTopologyId) ?? [];
+ }
+ selectionForSourceSymbol(symbol) {
+ return this._rangesBySource.get(symbol) ?? [];
}
selectionForEntity(entityId) {
const occurrences = this.mesh.occurrences.filter(item => item.semanticEntityId === entityId || item.definitionId === entityId);
const occurrenceIds = occurrences.map(item => item.id);
const definitionIds = new Set(occurrences.map(item => item.definitionId).filter(Boolean));
- const ranges = this.mesh.definitions.flatMap(definition => (definition.ranges ?? []).filter(range => range.semanticEntityId === entityId || definitionIds.has(definition.id)).map(range => ({ definitionId: definition.id, ...range })));
+ const ranges = [...(this._rangesByEntity.get(entityId) ?? [])];
+ for (const definitionId of definitionIds) for (const range of this._rangesByDefinition.get(definitionId) ?? []) if (!ranges.includes(range)) ranges.push(range);
return { occurrenceIds, ranges };
}
+ geometrySourceMap() { return this._geometrySourceMap; }
async exportSTEP(options = {}) {
throwIfAborted(options.signal);
const result = await this.transport.request({ operation: 'exportStep', sessionId: this.id });
diff --git a/Aetheris.Web.Runtime/sdk/tests/selection.test.mjs b/Aetheris.Web.Runtime/sdk/tests/selection.test.mjs
new file mode 100644
index 00000000..54e7d793
--- /dev/null
+++ b/Aetheris.Web.Runtime/sdk/tests/selection.test.mjs
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ModelSession } from '../src/index.js';
+
+test('display-only face identity never becomes a Firmament selector', () => {
+ const session = new ModelSession({}, {
+ mesh: {
+ definitions: [{ id: 'definition', ranges: [{ startTriangle: 0, triangleCount: 2,
+ faceId: 'face:5', semanticEntityId: 'body', sourceAddressability: 'RuntimeOnly',
+ selector: null, selectorReason: 'No authored topology mapping' }] }],
+ occurrences: [{ id: 'occurrence', definitionId: 'definition', semanticEntityId: 'body' }],
+ },
+ });
+ const selection = session.describeSelection('definition', 1, 'occurrence');
+ assert.equal(selection.faceId, 'face:5');
+ assert.equal(selection.selector, null);
+ assert.equal(selection.sourceAddressability, 'RuntimeOnly');
+ assert.equal(selection.selectorReason, 'No authored topology mapping');
+ assert.equal(session.describeSelection('definition', 2, 'occurrence'), null);
+});
+
+test('construction-owned face identity reaches picking and reverse source lookup', () => {
+ const source = { source: 'box.firmament', line: 3, column: 5, start: 32, length: 8 };
+ const range = { startTriangle: 0, triangleCount: 2, faceId: 'face:2', semanticEntityId: 'Body',
+ semanticTopologyId: 'Body.face(+Z)', topologyKind: 'Face', originFeature: 'Body',
+ sourceAddressability: 'DerivedStable', selector: 'face(+Z)', source, buildRevision: 4 };
+ const session = new ModelSession({}, { revision: 4, mesh: {
+ definitions: [{ id: 'definition', ranges: [range] }],
+ occurrences: [{ id: 'occurrence', definitionId: 'definition', semanticEntityId: 'Body' }],
+ } });
+ const picked = session.describeSelection('definition', 1, 'occurrence');
+ assert.equal(picked.semanticTopologyId, 'Body.face(+Z)');
+ assert.equal(picked.selector, 'face(+Z)');
+ assert.equal(picked.sourceAddressability, 'DerivedStable');
+ assert.equal(picked.sourceAddressable, true);
+ assert.deepEqual(picked.source, source);
+ assert.equal(picked.buildRevision, 4);
+ assert.deepEqual(session.selectionForSemanticId('Body.face(+Z)')[0].faceId, 'face:2');
+ assert.equal(session.selectionForSourceSymbol('Body').length, 1);
+ assert.equal(session.geometrySourceMap()[0].semanticKey, 'Body.face(+Z)');
+ assert.equal(session.geometrySourceMap()[0].source.start, 32);
+});
+
+test('BRep edges preserve construction metadata without inventing source selectors', () => {
+ const source = { source: 'box.firmament', line: 2, column: 3, start: 18, length: 42 };
+ const session = new ModelSession({}, { revision: 2, mesh: {
+ definitions: [{ id: 'definition', ranges: [], edges: [
+ { edgeId: 'edge:7', points: [[0, 0, 0], [1, 0, 0]], closed: false, semanticEntityId: 'Body', semanticTopologyId: 'Body.edge(TopFront)', sourceAddressability: 'DerivedStable', selector: null, selectorReason: 'No qualified edge selector', source },
+ { edgeId: 'edge:8', points: [[0, 0, 0], [0, 1, 0]], closed: false, sourceAddressability: 'RuntimeOnly', selector: null },
+ ] }],
+ occurrences: [{ id: 'occurrence', definitionId: 'definition', semanticEntityId: 'Body' }],
+ } });
+ const stable = session.describeEdgeSelection('definition', 'edge:7', 'occurrence');
+ assert.equal(stable.semanticTopologyId, 'Body.edge(TopFront)');
+ assert.deepEqual(stable.source, source);
+ assert.equal(stable.sourceAddressable, true);
+ assert.equal(stable.selector, null);
+ const runtime = session.describeEdgeSelection('definition', 'edge:8', 'occurrence');
+ assert.equal(runtime.semanticTopologyId, null);
+ assert.equal(runtime.sourceAddressability, 'RuntimeOnly');
+ assert.equal(runtime.selector, null);
+ assert.equal(session.geometrySourceMap().filter(item => item.topologyKind === 'Edge').length, 2);
+});
+
+test('a feature face keeps its owner inside a body occurrence', () => {
+ const source = { source: 'hole.firmament', line: 4, column: 2, start: 65, length: 94 };
+ const session = new ModelSession({}, { mesh: {
+ definitions: [{ id: 'definition', ranges: [{ startTriangle: 0, triangleCount: 1, faceId: 'face:7', semanticEntityId: 'Body.H',
+ semanticTopologyId: 'material:hole:Body.H:wall', sourceAddressability: 'DerivedStable', selector: 'face(H.Wall)', source }] }],
+ occurrences: [{ id: 'occurrence', definitionId: 'definition', semanticEntityId: 'Body' }],
+ } });
+ const picked = session.describeSelection('definition', 0, 'occurrence');
+ assert.equal(picked.semanticEntityId, 'Body.H');
+ assert.equal(picked.sourceAddressable, true);
+ assert.equal(picked.selector, 'face(H.Wall)');
+ assert.deepEqual(picked.source, source);
+ assert.equal(session.selectionForEntity('Body.H').ranges.length, 1);
+});
diff --git a/docs/public/firmament/pmi.md b/docs/public/firmament/pmi.md
index c7b602d1..a448cd24 100644
--- a/docs/public/firmament/pmi.md
+++ b/docs/public/firmament/pmi.md
@@ -4,6 +4,19 @@ Firmament concepts and explicit PMI lower into the semantic engineering model, S
Preview 3's native Model export supports `Datum` plane records and toleranced `HoleDiameter` records. The diameter record targets a named shaft hole; on a counterbore it means the shaft `Diameter`, not `CounterboreDiameter`. Other parsed PMI kinds may be reported as deferred and cannot be silently omitted by a successful build.
+For a simple `Hole<Shaft>` constructed in a Box, `face(H.Wall)` names the stable wall output of Hole `H`. It is a semantic role selector, independent of the current BRep face number. `HoleDiameter` accepts it as a target:
+
+```firmament
+Model WallReference {
+ Units: mm
+ Box Body { Size: [40mm, 30mm, 8mm] }
+ Modify Body { Hole<Shaft> H { On: +Z Center: Point2(0mm, 0mm) Diameter: 8mm End: ThroughAll } }
+ Pmi { HoleDiameter WallDiameter { Target: face(H.Wall) Value: 8mm } }
+}
+```
+
+The complete file is [`hole-wall-selector.firmament`](../../../fixtures/Canonical/PMI/hole-wall-selector.firmament). The compiler binds `H` as a Hole symbol, then resolves `Wall` through the construction-owned Hole-wall correspondence. Renaming `H` changes the selector spelling; diameter and position edits preserve it. Deleting `H` gives a Hole-specific unresolved-symbol diagnostic. Box `face(+Z)`, imported `face(#id)`, and existing PMI targets retain their meanings. `face(H.Wall)` is currently qualified for shaft walls in direct Box/Hole construction; it does not name blind bottoms, entry/exit rims, counterbore sections, patterned instances, or imported Hole-like faces. A planar `Datum` cannot consume a cylindrical Hole wall.
+
The complete qualified example is [`multiple-hole-dimensions-with-chamfer.firmament`](../../../fixtures/Canonical/PMI/multiple-hole-dimensions-with-chamfer.firmament):
```powershell
diff --git a/docs/public/firmament/wire-form.md b/docs/public/firmament/wire-form.md
index b7587e2b..a22f8442 100644
--- a/docs/public/firmament/wire-form.md
+++ b/docs/public/firmament/wire-form.md
@@ -29,10 +29,10 @@ Circular area times total length gives volume; density from the Material DB give
The centerline lowers to explicit line and circular-arc AIR, then to exact circular Sweep geometry. Straights become cylinders, bends become toroidal patches, and open terminals become planar caps. Canonical WireForms have no rational B-spline surfaces and no faceted fallback. Both terminals retain position, tangent/frame, and section diameter.
-WIRE-X1 adds semantic winding generators without weakening the exact Straight/Bend route. `AxisCoil` authors a cylindrical helix from `Radius`, `Turns`, either `Pitch` or `Height`, explicit `Handedness`, and an optional stable `StartPhase`. If both Pitch and Height are supplied they must agree with `Height = Turns × Pitch`. The compiler derives the missing value, exact helix length, terminal position/tangent/transported frame, turn clearance, volume, and mass.
+WIRE-X1 adds semantic winding generators without weakening the exact Straight/Bend route. `Helix` authors a cylindrical helix from `Radius`, `Turns`, either `Pitch` or `Height`, explicit `Handedness`, and an optional stable `StartPhase`. If both Pitch and Height are supplied they must agree with `Height = Turns × Pitch`. The compiler derives the missing value, exact helix length, terminal position/tangent/transported frame, turn clearance, volume, and mass. `AxisCoil` remains accepted as a compatibility spelling and lowers to the same semantic operation. The axis is derived from the current wire state rather than specified as an independent field.
```firmament
-AxisCoil Winding {
+Helix Winding {
Radius: 12mm
Turns: 8
Pitch: 5mm
@@ -61,15 +61,15 @@ The semantic/evaluable winding law remains authoritative. Coil-containing forms
X1 coils remain continuous, unbranched, open paths. WIRE-X2 adds a distinct closed `Knot` operation for named mathematical knot families; it does not turn coils into closed paths or force Straight/Bend through spline approximation. See [Mathematical Knots](mathematical-knots.md). Arbitrary/freeform supports, variable pitch or section, intentional contact, spring mechanics, contact dynamics, and branching remain unsupported. Surface support identity is authored rather than imported-face-ID based. Direct `Concept Path` plus `Sweep` remains the lower-level choice for explicitly authored line/arc trajectories.
-See the canonical [axis coil](../../../fixtures/Canonical/WireForm/axis-coil.firmament), [frustum SurfaceCoil](../../../fixtures/Canonical/WireForm/frustum-surface-coil.firmament), [sphere SurfaceCoil](../../../fixtures/Canonical/WireForm/sphere-surface-coil.firmament), [composed Straight/Coil/Straight](../../../fixtures/Canonical/WireForm/straight-coil-straight.firmament), [90-degree bend](../../../fixtures/Canonical/WireForm/single-bend-90.firmament), and [Paperclip](../../../fixtures/Canonical/WireForm/paperclip.firmament).
+See the canonical [Helix](../../../fixtures/Canonical/WireForm/helix.firmament), [AxisCoil compatibility fixture](../../../fixtures/Canonical/WireForm/axis-coil.firmament), [frustum SurfaceCoil](../../../fixtures/Canonical/WireForm/frustum-surface-coil.firmament), [sphere SurfaceCoil](../../../fixtures/Canonical/WireForm/sphere-surface-coil.firmament), [composed Straight/Coil/Straight](../../../fixtures/Canonical/WireForm/straight-coil-straight.firmament), [90-degree bend](../../../fixtures/Canonical/WireForm/single-bend-90.firmament), and [Paperclip](../../../fixtures/Canonical/WireForm/paperclip.firmament).
`aetheris inspect source.firmament --json` reports the semantic `wireForm` object, including `operations`, `totalStraightLength`, `totalBendLength`, and compiler-derived `totalWireLength`. A materializing `build --json` adds volume, mass, surface inventory, manifold/reimport status, rational/faceted counts, and the STEP hash.
## Mating a coil to a rod
-An `AxisCoil` starts at the current wire point and preserves its tangent. Its winding axis is generally **offset from that point and tilted from StartFrame.Up**: pitch contributes an axial component to the tangent. Do not mate the part origin or assume local Z is the spring axis.
+A `Helix` starts at the current wire point and preserves its tangent. Its winding axis is generally **offset from that point and tilted from StartFrame.Up**: pitch contributes an axial component to the tangent. Do not mate the part origin or assume local Z is the spring axis.
-Executable Assembly template occurrences now expose each `AxisCoil` operation by its authored name. For `AxisCoil Winding`, the public semantic members are `Winding.Axis`, `Winding.Frame` and `Winding.ClearDiameter`. They come from the same compiler-derived axis origin, direction, start radial and wire radius that build the coil. The frame's Z axis is the winding axis, X is its start radial, and its origin is the winding-axis base. Clear diameter is twice the coil centerline radius minus wire diameter. The build report retains these values as `wireForm.operations[].axisDatum`.
+Executable Assembly template occurrences expose each `Helix` operation by its authored name. For `Helix Winding`, the public semantic members are `Winding.Axis`, `Winding.Frame` and `Winding.ClearDiameter`. They come from the same compiler-derived axis origin, direction, start radial and wire radius that build the coil. The frame's Z axis is the winding axis, X is its start radial, and its origin is the winding-axis base. Clear diameter is twice the coil centerline radius minus wire diameter. The build report retains these values as `wireForm.operations[].axisDatum`.
A bounded spring-to-rod interface can combine axial alignment with a seating frame:
@@ -83,4 +83,4 @@ Interface SpringOnRod {
}
```
-The datum frame fixes axial seat position and roll; the explicit axis constraint independently validates coaxiality after materialization. Fit analysis classifies diameter compatibility. See the executable [coil-on-stem fixture](../../../fixtures/Canonical/Assembly/coil-on-stem.firmament). This automatic datum exposure currently covers `AxisCoil`; it does not infer an axis for knots or arbitrary SurfaceCoil supports.
+The datum frame fixes axial seat position and roll; the explicit axis constraint independently validates coaxiality after materialization. Fit analysis classifies diameter compatibility. See the executable [coil-on-stem fixture](../../../fixtures/Canonical/Assembly/coil-on-stem.firmament). This automatic datum exposure covers `Helix` and its `AxisCoil` compatibility spelling; it does not infer an axis for knots or arbitrary SurfaceCoil supports.
diff --git a/docs/public/reference/supported-features.md b/docs/public/reference/supported-features.md
index 31c1c598..bdc910f2 100644
--- a/docs/public/reference/supported-features.md
+++ b/docs/public/reference/supported-features.md
@@ -14,7 +14,7 @@
| Circular Sweep | Bounded (X0) | Open planar XY Concept Path, tangent line/arc segments, constant circular diameter, analytic cylinder/torus faces, capped solid; no general 3D/variable/rail/twist sweep |
| Revolve | Bounded (X1) | One bounded outer line/arc Profile, explicit coplanar Axis, `0 < \|Angle\| <= full`, signed direction, safe Base construction; no multi-turn, axis-crossing, general axis-touching, inner loops, Add/Remove, or skew projection |
| Profile/Path `|>` composition | Supported (LANG-PIPELINE-X1) | finite qualified span chains, automatic continuity orientation, `Reverse`, `As`, validating `Close`, real-loop-only `TraceLoop`, inherited identity/provenance; no general function pipe or control flow |
-| Wire coils | Bounded (WIRE-X1) | Semantic AxisCoil plus Cylinder/Frustum/Sphere SurfaceCoil, explicit handedness/clearance, constant circular wire, evaluable winding authority, deterministic cubic non-rational STEP tube; no variable pitch/section, arbitrary support, intentional contact, dynamics, or knots |
+| Wire coils | Bounded (WIRE-X1) | Semantic `Helix` (`AxisCoil` compatibility spelling) plus Cylinder/Frustum/Sphere SurfaceCoil, explicit handedness/clearance, constant circular wire, evaluable winding authority, deterministic cubic non-rational STEP tube; no variable pitch/section, arbitrary support, intentional contact, or dynamics |
| Formed Wire | Bounded (WIRE-X0) | One open, continuous, unbranched constant circular wire; explicit 3D StartFrame; ordered Straight and signed planar Bend operations through ±180° in current local Up/Right planes; exact line/arc centerline, ideal cut length/volume/mass, analytic cylinders/tori/caps, terminals, and fail-closed no-contact validation. No coils, knots, branches, variable section, springback, or intentional contact. See [guide](../firmament/wire-form.md). |
| SectionChain loft substrate | Bounded (SURF-X4 subset) | Firmament authoring lowers into ordered framed, same-topology semantic SectionChain IR; explicit G0 ruled or default G1 local polynomial transitions; shared edges and tangent fields; Cap/Open; strict pcurves; deterministic intersection checks; persistent typed BodyState Add/Remove through documented planar housing lanes; no generic CSG authoring, rational product surface, or faceted fallback. See [Section chains](../firmament/section-chains.md). |
| `Loft` and `Loft<Hollow>` | Bounded two-section circle/ellipse profiles | Two framed outlines, straight ruled generators, `CommonRay` correspondence, and optional `Twist` (-180° to 180°). `Loft` makes a capped solid; `Loft<Hollow>` adds nominal wall thickness and a narrow explicit seam. Both lower through SectionChain to closed AP242 solids. See [Loft](../firmament/loft.md). |
@@ -40,7 +40,7 @@
| Platform qualification | Supported | Windows x64 bundle; NativeAOT Forge Host on `win-x64` |
| Linux/macOS release binaries | Not in Preview 3 | Framework logic tests do not constitute binary qualification |
| Post-Preview-3 feature families | X0 exception | Circular Sweep, WIRE-X0 Formed Wire, and Standard Products Paperclip are bounded X0 additions; other new geometry/PMI/FEA/Forge families remain frozen |
-| General smooth/rail/topology-changing loft, helix, and freeform surface features | Not in Preview 3 | The bounded two-section lofts and G1 SectionChains do not qualify arbitrary smooth loft, guide rails, topology-changing correspondence, arbitrary dumb-solid editing, G2 continuity, or surface networks. |
+| General smooth/rail/topology-changing loft and freeform surface features | Not in Preview 3 | The bounded two-section lofts, G1 SectionChains, and WireForm `Helix` do not qualify arbitrary smooth loft, guide rails, topology-changing correspondence, arbitrary dumb-solid editing, G2 continuity, or surface networks. |
| Through profile removal | Bounded semantic operations | Use qualified `Hole`, `Slot`, or another documented opening feature; Pocket never means through-all |
| Arbitrary solid Boolean subtraction / hemispherical cavity | Not in Preview 3 | No public `Union`, `Subtract`, `Intersect`, CSG tree, Sphere-from-Block subtraction, or hemisphere special case |
diff --git a/docs/release/FIRMAMENT-HOLE-SELECTOR-X0.md b/docs/release/FIRMAMENT-HOLE-SELECTOR-X0.md
new file mode 100644
index 00000000..bb7db31d
--- /dev/null
+++ b/docs/release/FIRMAMENT-HOLE-SELECTOR-X0.md
@@ -0,0 +1,31 @@
+# FIRMAMENT-HOLE-SELECTOR-X0 — canonical Hole wall selection
+
+Verdict: **Accepted for the bounded shaft-wall contract.** A compiler-owned Hole wall formats as `face(H.Wall)`, parses into a typed `FirmamentV2HoleWallSelector`, binds `H` to the semantic Hole declaration, and resolves the `HoleWallFace` role against current construction correspondence. `HoleDiameter` PMI is the existing legal use site. Helios copies the Aetheris-provided selector and rebuilds source containing that PMI record with zero diagnostics.
+
+## Grammar audit
+
+The older `Selection WallH { Target: HoleWall Source: Hole(H) Require: NonEmptyFaceSet }` is part of the advanced profile/compose selection grammar. The `Selection` keyword dispatches a simple Box + Hole file into the advanced adapter, where that body fails with `firmament-v2-phase3-edge-finish-syntax-invalid`. It was a named selection declaration, not a short target expression consumable by native PMI. X0 adds only `face(<HoleName>.Wall)` as a Hole-wall target for `HoleDiameter`; it does not change or alias the advanced declaration grammar. Existing axis `face(+Z)`, imported `face(#id)`, and named-hole PMI targets remain on their existing paths.
+
+## Round trip
+
+| Stage | Evidence |
+| --- | --- |
+| Construction | `Hole<Shaft> H` lowers to feature `Body.H`; wall descendant has `HoleWallFace`, source `hole:Body.H`, and a BRep face ID. |
+| Format | The formatter requires that role, source feature, face, and stable addressability; it emits `face(H.Wall)` from the Hole name. |
+| Parse/bind | Native PMI parsing records typed `FirmamentV2HoleWallSelector(H, Body)`. Unknown, non-Hole, and ambiguous symbols have distinct diagnostics. |
+| Resolve | `SemanticTopologySelectionResolver` resolves source `hole:Body.H` plus `HoleWallFace` to the current face set. It permits one semantic role to have several faces. |
+| Use | `HoleDiameter WallDiameter { Target: face(H.Wall) Value: 8mm }` exports normal AP242 diameter PMI bound to the selected Hole. |
+
+For two shaft Holes, the bounded Boolean builder reports each wall's feature ID and face ID **when the face is constructed**. The composite materializer carries both roles into the direct display map; `face(H1.Wall)` and `face(H2.Wall)` stay distinct. No cylinder recognition or STEP reimport provides source identity.
+
+## Helios and verification
+
+The browser witness picks the inside wall, sees `Body.H`, copies `face(H.Wall)`, navigates to the Hole declaration, selects that declaration, edits the diameter, picks the wall again, uses `Reference Hole Wall in Source`, pastes the copied selector into its `HoleDiameter` target, and rebuilds with zero diagnostics. Helios withholds its planar `Reference Face in Source` action for the cylindrical wall. Web SDK selection exposes the selector, source range, role, origin feature, and build revision.
+
+A fresh UI-only run created a Box + Hole project, clicked the inside wall, and saw `Body.HeliosHole1`, `HoleWallFace`, and `face(HeliosHole1.Wall)` in the Inspector. `Reference Hole Wall in Source` inserted `Pmi { HoleDiameter SelectedWall1 { Target: face(HeliosHole1.Wall) Value: 6mm } }`; rebuild completed with zero diagnostics. The tester used only the UI and did not inspect the source grammar or parser. The first blind run had exposed the missing discoverable use-site action, which the contextual Inspector action now supplies.
+
+Focused native tests cover format/parse/bind/resolve, STEP reimport, diameter and position edits, rename, deletion, non-Hole diagnostics, and two named Holes. Browser Box and Hole tests cover the actual pick/copy/paste/rebuild path. Existing PMI/FEA/SheetMetal suites are regression gates.
+
+## Limits
+
+Blind-hole Bottom, entry/exit rims, counterbore sections, patterned-hole instance selectors, and imported Hole-like topology are outside X0. The typed PMI target is qualified only for `HoleDiameter`; a cylindrical wall is not admitted as a planar Datum. The current direct source map has one primary origin per wall and does not claim universal topological naming.
diff --git a/docs/release/FIRMAMENT-LX-X0.md b/docs/release/FIRMAMENT-LX-X0.md
new file mode 100644
index 00000000..88a5b3b9
--- /dev/null
+++ b/docs/release/FIRMAMENT-LX-X0.md
@@ -0,0 +1,49 @@
+# Firmament LX-X0 — language experience and semantic selector contract
+
+**Verdict: Blocked.** The requested accepted contract cannot be implemented within the mission's own constraints against new Firmament syntax, a second language definition, and selectors derived from transient mesh IDs. This report records the precise boundary; no compiler, Web SDK, or Helios behavior was changed.
+
+## Decisive witnesses
+
+| Required witness | Current authoritative behavior | Evidence |
+| --- | --- | --- |
+| `Helix H { ... }` completion and valid snippet | The Mechanical parser rejects `Helix` as an unknown canonical declaration. | `dotnet run --project Aetheris.CLI -- validate artifacts/local/lx-x0/helix-probe.firmament --json` returned fatal `firmament-v2-canonical-declaration-unknown:Helix`. `FirmamentV2Parser.ScanCanonicalTopLevelDeclarations` has no Helix admission. |
+| Existing helical authoring | `AxisCoil` is valid inside a `WireForm`, with Radius, Turns, Pitch or Height, Handedness, and optional StartPhase. It is a different admitted construct, not a `Helix` alias. | `dotnet run --project Aetheris.CLI -- validate fixtures/Canonical/WireForm/axis-coil.firmament --json` returned `status: valid`, 0 diagnostics, 1 operation. See `docs/public/firmament/wire-form.md`. |
+| Runtime face → source selector | The Web SDK emits `face:<FaceId.Value>` from tessellated/reimported B-rep faces and returns it from `resolveSelection`. It has no compiler-owned correspondence from that ID to an authored axis/name/selector. | `Aetheris.Web.Runtime/Program.cs`, `WebMeshBuilder.Build`; `Aetheris.Web.Runtime/sdk/src/index.js`, `ModelSession.resolveSelection`. |
+| Runtime edge → source selector | The V2 parser explicitly rejects `edge(...)` exposure selectors. | `FirmamentV2Parser.ParseExposures` adds `SelectorUnsupported` for `edge(...)`; `FirmamentV2ParserTests` qualifies that rejection. |
+| Geometry → precise source | The Web part snapshot gives the root and body the entire source range. Engineering feature nodes have `source: null`; mesh ranges carry the same body entity ID. | `Aetheris.Web.Runtime/Program.cs`, `WebModelSession.CompilePart`. |
+| Precise diagnostics | The Web runtime maps `KernelDiagnostic.Source` to `details` and assigns every diagnostic a synthetic `SourceRef(sourceName, 0, 0)` (line 1, column 1). `KernelDiagnostic` has no range field. | `Aetheris.Web.Runtime/Program.cs`, `Diagnostics`; `Aetheris.Kernel.Core/Diagnostics/KernelDiagnostic.cs`. |
+
+## Language intelligence
+
+The existing V2 parser and specialized authoring parsers remain authoritative, but there is no public partial-source language-service API. `FirmamentV2Parser.Parse` is a whole-document parse and returns diagnostic codes and a semantic document after expansion. Its canonical construct admission list is internal to the parser. Many constructs are governed by separate specialized parsers and frontend schemas. A separate TypeScript completion table would drift immediately; a new C# table that merely restates these parsers would also be a second language definition.
+
+Current Web SDK methods are `compile`, session rebuild/property/source operations, tree and mesh inspection, selection resolution, and STEP export. It exposes no completion, hover, signature help, symbol/definition/reference query, or partial-source diagnostic request. No LX result shape or latency is claimed. There is no measured completion/hover/selector latency because the APIs do not exist.
+
+## Selector semantics
+
+The parser accepts semantic axis forms such as `face(+Z)` in supported contexts, and imported STEP uses `Body.face("#entity")` only where an imported topology map resolves that entity. These are source expressions. A browser `face:5` identity is neither form. Mapping a selected face to `face(+Z)` would require compiler-owned evidence that the selected topology is the unique source-addressable +Z face for the relevant authored body and revision. The Web export currently retains no such mapping. Mapping an edge needs an admitted source selector form first; the parser currently rejects it.
+
+Therefore source-addressability cannot be asserted from the current Web selection result. A conservative API could report `Ambiguous` or `RuntimeOnly` with no selector, but it would not satisfy the mandatory face/edge acceptance witnesses or the fresh-agent Copy Selector task. Returning fabricated text would make the user paste invalid Firmament.
+
+## Helios implication
+
+Helios should keep **Copy Semantic ID** distinct from **Copy Selector**. The prior DFH-X1 UI-only walkthrough confirmed why: a selected top face displayed `face:5`; using that value as a Hole `On` expression failed. Go to Source selected model-level line 1 rather than the Box declaration at line 3. Helios's hardcoded Box/Hole snippets are a narrow interim authoring aid, not an LX contract. Replacing them requires authoritative snippet/field metadata and a partial-source analysis path in Aetheris.
+
+## Required upstream decisions and work
+
+1. Decide whether LX-X0 targets the currently admitted **AxisCoil** helical workflow or authorizes a separate **Helix** language and geometry milestone. The present mission asks for Helix while prohibiting the syntax/geometry work needed to make it legal.
+2. Retain authored declaration spans and generated semantic-to-topology provenance through Firmament AIR, B-rep, STEP reimport, and the Web mesh. This must support one source construct to many faces/edges and distinguish addressable from generated/runtime-only topology.
+3. Define and admit source-valid selector forms for the intended face and edge classes. The formatter must consume the compiler's stable identities, not reimported face numbers or mesh indexes.
+4. Add parser-adjacent authoring metadata or reusable parser queries for fields, value kinds, snippets, and partial-source contexts; expose revision-tagged JSON-safe results through the Web SDK. Preserve the actual parser/binder as the only language authority.
+5. Carry precise source spans through diagnostics instead of assigning line 1 to every Web diagnostic. Then qualify incomplete-source completion and diagnostics without B-rep rebuild.
+
+This is upstream semantic/compiler work, not a safe Helios-only patch. The existing single-source Web contract and missing project context remain additional limitations. No multi-file work, language redesign, or geometry test weakening was introduced.
+
+## Qualification performed
+
+- Aetheris CLI help inspected before assumptions, per repository guidance.
+- Canonical AxisCoil fixture validated through the real CLI: valid, 0 diagnostics.
+- A Mechanical `Helix` probe under ignored `artifacts/local/lx-x0/` validated through the real CLI: fatal unknown declaration.
+- Existing parser test source confirms `edge(...)` rejection. No implementation files changed, so full solution/browser/Helios regression was not run for this blocked audit.
+
+**Decision boundary:** Resume implementation after the Helix versus AxisCoil target and stable face/edge selector semantics are explicitly admitted by the owning compiler. An editor contract can then project those authorities without duplicating Firmament.
diff --git a/docs/release/FIRMAMENT-UX-SURFACE-X0.md b/docs/release/FIRMAMENT-UX-SURFACE-X0.md
new file mode 100644
index 00000000..e6d0959d
--- /dev/null
+++ b/docs/release/FIRMAMENT-UX-SURFACE-X0.md
@@ -0,0 +1,33 @@
+# FIRMAMENT-UX-SURFACE-X0 — Helix admission and topology selector audit
+
+## Verdict: Meaningful progression
+
+`Helix` is admitted as the canonical WireForm operation. `AxisCoil` remains a source compatibility spelling. Both invoke `WireCoilAuthoring.CreateAxis`, produce the same `WireAxisCoilAir`, stable operation ID, and evaluable geometry. Public build/inspect metadata now calls this operation `Helix`.
+
+Source-valid selectors for arbitrary picked topology remain incomplete. The Web runtime compiles a part to STEP, reimports that STEP, tessellates the imported body, and emits `face:<FaceId.Value>` on display ranges. The compiler does not carry an authored face/edge correspondence through that boundary. Formatting the displayed number as `face(#id)`, `face(+Z)`, or an imported STEP selector would assert identity that is not established. The runtime therefore labels these ranges `RuntimeOnly` with a null selector and an explicit reason; `ModelSession.describeSelection` exposes the classification.
+
+## Admitted Helix surface
+
+- `Helix Name { Radius; Turns; Pitch or Height; Handedness; StartPhase }` inside `WireForm` uses normal Firmament length/angle parsing. Radius, Turns, and pitch/height must be positive. If Pitch and Height are both present, Height must equal Turns × Pitch. Handedness is `RightHanded` or `LeftHanded`. The winding axis is derived from the incoming wire state.
+- The canonical fixture is `fixtures/Canonical/WireForm/helix.firmament`; `axis-coil.firmament` remains the compatibility witness. Public WireForm documentation teaches Helix first.
+- Helios has a `New Helix Model` command palette entry that opens a complete one-turn WireForm source. This is a bounded witness, not a language completion service. The WebAssembly material resolver reads the same checked-in immutable catalog seed through the existing validation/mapping code because the EF/SQLite compiled model cannot initialize in the browser. Helios retains its page-lifetime WebAssembly transport across project sessions; the local SDK installer refreshes a changed preview tarball instead of silently keeping an old package.
+
+## Selector identity findings
+
+- `face(+Z)` is a typed `FirmamentV2FaceSelector` for bounded authored box-face uses. Imported STEP has a separate qualified `Body.face("#entity")` target and an imported topology map. Those identities do not currently map to Web display face IDs.
+- The V2 exposure parser explicitly rejects `edge(...)` and has no general body selector. Face, edge, and body formatter/parser/binder roundtrips therefore cannot be claimed.
+- Web source references are currently attached to root/body source ranges; generated display faces have no originating feature range. Assembly display ranges also lack a source-selector correspondence.
+- The next blocker is an authoritative export/reimport correspondence from compiler-owned semantic face and edge identity to displayed topology, followed by a bounded parser/binder contract for each admitted selector kind. Numbering by tessellation or reimport order would be unstable.
+
+## Verification
+
+- `dotnet test Aetheris.Kernel.Firmament.Tests --filter FullyQualifiedName~WireFormTests --no-restore`: 30 passed, including Helix/AxisCoil AIR and stable-ID parity, handedness, derived pitch, invalid dimensions, and STEP build.
+- `dotnet run --project Aetheris.CLI -- build fixtures/Canonical/WireForm/helix.firmament --json`: success; enclosed manifold, STEP reimport manifold, 1 Helix operation, zero faceted fallback; generated fixture STEP was removed after inspection.
+- `dotnet test Aetheris.Kernel.Firmament.Tests --filter 'FullyQualifiedName~FirmamentV2InlineStepTests|FullyQualifiedName~FirmamentV2CanonicalSafetyAndLabelingTests' --no-restore`: 62 passed; existing imported STEP selectors remain intact.
+- `dotnet build Aetheris.Web.Runtime --no-restore` and Web SDK `npm run build`: succeeded with existing WebAssembly/analyzer warnings.
+- Material catalog tests: 5 passed. Helios `npm run build` and focused `HeliosApp.test.tsx`: succeeded, 9 tests passed.
+- Helios Playwright `tests/helix-palette.spec.ts`: passed against the installed SDK/WASM and real project UI; the palette opened Helix source, produced 1 display definition, and finished with zero diagnostics (48.7 seconds). The one-turn snippet bounds browser compile cost; the eight-turn fixture is qualified by CLI, not by this browser run.
+- SDK `node --test tests/selection.test.mjs` passed: `face:5` returns `RuntimeOnly` and no selector; an out-of-range triangle returns null.
+- A fresh agent independently used CLI validate/inspect/build on the Helix fixture: 0 validation diagnostics, 1,026 manifold faces, successful STEP reimport, and no faceted fallback. A source probe using a previously displayed `face:5` failed in parsing; changing the face target to `+Z` built successfully. The separate browser witness above verifies the Helix palette after the fresh agent's initial URL probe was unavailable.
+
+The current result is deliberately short of selector acceptance and Copy Selector. No editor-specific selector spelling was introduced.
diff --git a/docs/release/GEOM-SOURCEMAP-X0.md b/docs/release/GEOM-SOURCEMAP-X0.md
new file mode 100644
index 00000000..3adfaeb0
--- /dev/null
+++ b/docs/release/GEOM-SOURCEMAP-X0.md
@@ -0,0 +1,30 @@
+# GEOM-SOURCEMAP-X0 — compiler-owned geometry provenance
+
+Verdict: **Meaningful progression**. Box and one simple through Hole carry construction-owned semantic identity and compiler source spans into the direct BRep display path. Extrude, Boss, and Pocket do not yet have qualified Web source maps, and Hole wall has no parser/binder-qualified source selector.
+
+## Authority and propagation
+
+The V2 parser records the Box construct span. Semantic Hole declarations already have parser spans. Materialization assigns stable output roles to BRep face/edge IDs; `SemanticTopologyCorrespondence` carries these roles and spans for one build. `GeometrySourceMap` indexes BRep face/edge to provenance and semantic key/source symbol back to descendants. It rejects duplicate BRep entity mappings and permits multiple entities under one semantic key. The Web runtime tessellates the **same BRep body**, copies correspondence onto face triangle ranges and true BRep edge polylines, and includes a build revision. Web SDK picking reads the owning range or edge record directly. The SDK rebuild replaces its indexes, and Helios clears selected topology after a successful rebuild.
+
+The semantic key is a construction role such as `Body.face(+Z)` or `material:hole:Body.H:wall`; it is independent of BRep ordinal. The current map has one primary origin per entity. It does not claim contributor chains or provenance through STEP export/reimport. Unmapped imported/display topology remains `RuntimeOnly` with no selector or source range. `geometrySourceMap()` exposes a compact diagnostic dump. SDK reverse indexes support semantic key, source symbol, and entity lookup.
+
+| Feature | Construction roles and BRep | Display pick | Selector |
+| --- | --- | --- | --- |
+| Box | Six named faces and construction edges; parser Box span | Qualified direct BRep patches and edges | `face(±X/±Y/±Z)` for faces; existing PMI binder accepts it. Edges withheld. |
+| Simple through Hole | Wall face, entry/exit loops and edges; parser Hole span | Wall and true rim edges carry `Body.H` owner | Withheld: simple Hole grammar rejects advanced `Selection ... HoleWall` declaration. |
+| Extrude | Existing profile construction roles in other paths | Not qualified for this Web route | Not claimed. |
+| Boss | No qualified X0 path | Not qualified | Not claimed. |
+| Pocket | No qualified X0 path | Not qualified | Not claimed. |
+
+## Helios witness
+
+The browser Box test picks top `+Z`, copies `face(+Z)`, navigates to the compiler Box span, and rebuilds a model containing that selector. It also picks a real BRep edge with no invented selector. The Hole browser test picks the inside wall as `Body.H`, navigates to the Hole declaration, selects that declaration to recover the Hole feature, and repeats the pick after a diameter edit. Hole Copy Selector remains disabled. This is the exact remaining blocker for the fresh-agent “reference the inside wall in code” task; no STEP recognition or fabricated selector is used.
+
+## Evidence and limits
+
+- `BoxRuntimeCorrespondenceTests` and `HoleRuntimeCorrespondenceTests`: eight focused native tests pass, including source spans, direct BRep mapping, size/diameter identity, duplicate-entity rejection, one-to-many index behavior, STEP reimport, top tessellation area, and the Hole grammar rejection.
+- Web SDK selection tests: four pass; browser Box/Hole tests pass using the locally repackaged WASM SDK.
+- Existing PMI CLI, FEA, and SheetMetal regression gates passed during this work; they were run before the final source-map index edits, which do not change their execution paths.
+- No construction-overhead or pick-latency benchmark has been established. Index lookups are dictionary based; no measured performance claim is made.
+
+Next blocker: give Hole wall a canonical Firmament selector with parser, binder, and semantic resolution round trip. Extend construction roles through the real Extrude/Boss/Pocket paths before claiming full X0 acceptance.
diff --git a/docs/release/SEMANTIC-CORRESPONDENCE-X1.md b/docs/release/SEMANTIC-CORRESPONDENCE-X1.md
new file mode 100644
index 00000000..a692a831
--- /dev/null
+++ b/docs/release/SEMANTIC-CORRESPONDENCE-X1.md
@@ -0,0 +1,53 @@
+# SEMANTIC-CORRESPONDENCE-X1
+
+## Executive verdict
+
+**Meaningful progression.** A plain, single Box now carries construction-owned face identity from Firmament through canonical BRep tessellation to Web SDK picking and Helios selector copy/source navigation. The browser witness picked a top and side face, retained `Body.face(+Z)` after a size edit, and rebuilt a Datum reference to the picked face. Hole walls, source-addressable edges, and STEP reimport correspondence are still missing, so the full X1 acceptance criteria are not met.
+
+## Identity inventory and authority
+
+| Layer | Identity in this milestone | Authority and limit |
+| --- | --- | --- |
+| Firmament source / AIR | Box feature name and lowered primitive feature ID | Authored feature identity; a Box declaration source range is attached to the Web tree and face ranges. |
+| BRep | `FaceId`, `EdgeId`, `BrepExtrudeConstructionTopology` | IDs are exact within a constructed body. They are not persistent selectors by themselves. The extrusion now captures the IDs it creates. |
+| Semantic topology | `SemanticTopologyCorrespondence` and descendants | Existing Firmament correspondence type; Box descendants bind stable role IDs to captured BRep IDs. Other producers already use this type for selection/PMI, but no general Web bridge is asserted. |
+| PMI / FEA | Existing axis face targets and semantic selection resolver | `face(+Z)` parses in the existing PMI path. This work does not change FEA selectors or PMI association. |
+| STEP AP242 | Exported geometry and existing PMI references | STEP export still works and reimports. The imported `FaceId` and STEP entity numbers are not treated as the authored Box face identity. |
+| Web display | Tessellation `FacePatch.FaceId`, triangle ranges | A patch joins to correspondence only by the same canonical BRep `FaceId`. Triangle indices and patch order only locate a range; they do not create selectors. |
+| Forge / imported bodies / sheet metal | Existing host or import identities | No new source correspondence is claimed for these routes. Imported source-less geometry remains non-addressable in this Web path. |
+
+## Actual chain and architecture choice
+
+For the admitted single-Box route:
+
+`Box Body` → lowered Box feature `Body` → `BrepPrimitives.CreateBoxWithTopology` → captured extrusion face IDs → `BoxConstructionCorrespondence` → direct canonical BRep tessellation → Web mesh face range → SDK `describeSelection` → Helios Inspector `Copy Selector` / `Go to Source`.
+
+The Web runtime still produces AP242 STEP for export. It displays the already constructed BRep for this route because reimport assigns new runtime topology IDs and has no qualified source-to-import map. A direct in-process BRep reference is smaller and more reliable than encoding metadata into STEP or matching imported faces by centroid, area, or order. Other feature families continue through the existing STEP reimport display path. A sidecar keyed to STEP entities was not introduced because it would require deterministic export/import entity correspondence and validation that this milestone has not established.
+
+The map lives in `FirmamentStepExportResult.RuntimeCorrespondence` beside `RuntimeBody`; both are excluded from JSON. Web mesh ranges carry the semantic ID, source selector, source reference, addressability, and build revision. A new successful rebuild creates new ranges; old selections are cleared in Helios. A changed Box size retains semantic role IDs; renaming the Box changes its semantic IDs. Helios offers **Reference Face in Source** for an admitted axis face; it inserts an existing `Pmi { Datum ... { Target: face(+Z) } }` construct. The generated Hole `On:` field uses a different grammar and does not accept this selector.
+
+## Coverage
+
+| Family | Body | Face | Edge | Web selector |
+| --- | --- | --- | --- | --- |
+| Single Box without modifying features | Feature ID and declaration source | Six construction-bound axis faces, `DerivedStable` | One captured top-front edge ID, no source syntax | Axis face selectors only |
+| Box with Hole / Hole wall | Existing feature identity | Runtime display IDs; existing producer correspondence is not transported by this route | Runtime only | No trusted display selector |
+| Boss / Pocket / Loft / Sweep / Revolve | Existing compiler identities where present | No Web correspondence qualified | No Web correspondence qualified | None claimed |
+| Sheet metal | Existing kernel semantic identities | No Web correspondence qualified | No Web correspondence qualified | None claimed |
+| Imported STEP / Forge | Host or import identity where available | Reimported display topology has no source mapping | Same | None claimed |
+| Synthetic display-only face | Runtime entity | `RuntimeOnly` | Runtime only | No selector |
+
+An edge is captured from construction, but `edge(TopFront)` is **not** emitted as Firmament syntax because the admitted parser has no corresponding edge selector. No Hole wall selector is invented. Face role names come from the Box profile's explicit ordered corners and the extrusion's ordered side construction; no post-build geometry search assigns them.
+
+## Verification
+
+- `dotnet test Aetheris.Kernel.Firmament.Tests --filter FullyQualifiedName~BoxRuntimeCorrespondenceTests --no-restore -v:q`: 4 passed. Covers six exact face bindings and their surface normals, size/rename identity behavior, existing PMI face syntax parsing and compilation, and STEP export/reimport of six faces.
+- `node --test tests/selection.test.mjs` in the Web SDK: 2 passed. Covers mapped selection/reverse lookup and RuntimeOnly selector refusal.
+- `npm run sdk:install`, `npm run build`, `npm test -- --run` in HeliosCAD: succeeded; 26 UI tests passed.
+- `dotnet test Aetheris.CLI.Tests --filter FullyQualifiedName~FirmamentV2SemanticPmiStepPipelineTests --no-restore -v:q`: 2 passed. `dotnet test Aetheris.Kernel.Core.Tests --filter FullyQualifiedName~PmiModelTests --no-restore -v:q`: 5 passed. `dotnet test Aetheris.FEA.Tests --no-restore -v:q`: 43 passed. `dotnet test Aetheris.SheetMetal.Tests --no-restore -v:q`: 99 passed.
+- `npx playwright test tests/box-correspondence.spec.ts --reporter=line` in HeliosCAD: passed in Chromium against the installed WASM package. It picked the top face, copied `face(+Z)`, navigated to the Box declaration, picked a side face, selected the source feature, rebuilt after a size edit, found `Body.face(+Z)` again, inserted a Datum reference from the Inspector, and rebuilt with zero diagnostics.
+- An independent UI-only attempt first copied the face selector but pasted it into the generated Hole `On:` field, which is not a valid selector context. This exposed the missing affordance and motivated **Reference Face in Source**. In a fresh UI-only retest, that button inserted `Pmi { Datum SelectedFace1 { Target: face(+Z) } }`; Rebuild reached revision 3 with zero Problems and the tester saved the project. The tester reported that TOP view looked triangular despite selecting the correct `Body.face(+Z)` face; that visual observation is not yet diagnosed.
+
+## Remaining acceptance gaps
+
+The current selector proof covers existing `face(+Z)` PMI parsing/compilation and browser source insertion. It does not prove that every accepted selector context resolves to the same BRep face; PMI association needs a stronger end-to-end topology assertion. Body selection uses the authored feature ID, but there is no standalone canonical body selector text. Edge source syntax and Hole wall correspondence are absent. STEP reimport remains geometrically verified but semantically lossy. Full X1 acceptance therefore remains open.
diff --git a/fixtures/Canonical/PMI/hole-wall-selector.firmament b/fixtures/Canonical/PMI/hole-wall-selector.firmament
new file mode 100644
index 00000000..20a792a4
--- /dev/null
+++ b/fixtures/Canonical/PMI/hole-wall-selector.firmament
@@ -0,0 +1,10 @@
+Model WallReference {
+ Units: mm
+ Box Body { Size: [40mm, 30mm, 8mm] }
+ Modify Body {
+ Hole<Shaft> H { On: +Z Center: Point2(0mm, 0mm) Diameter: 8mm End: ThroughAll }
+ }
+ Pmi {
+ HoleDiameter WallDiameter { Target: face(H.Wall) Value: 8mm }
+ }
+}
diff --git a/fixtures/Canonical/README.md b/fixtures/Canonical/README.md
index dad35cb0..6874540d 100644
--- a/fixtures/Canonical/README.md
+++ b/fixtures/Canonical/README.md
@@ -36,7 +36,7 @@ Everything in this directory is current authoring guidance. Examples progress fr
| route a piping system | `Piping/pump-skid.firmament` | logical Connection, equipment-owned nozzle Interfaces/mates, scoped owner exemption, explicit/accepted Routes, strict foreign KeepOut clearance, fittings, BOM/Cut List |
| combine machining operations | `Integration/machined-mounting-block.firmament` | Boss, Pocket, holes, counterbores, chamfer, PMI |
-`Pocket` never means through-all; use a supported `Hole` or `Slot` for through removal. Bounded two-section [`Loft` and `Loft<Hollow>`](../../docs/public/firmament/loft.md) are admitted; general smooth/rail loft, helix, arbitrary Boolean authoring, and freeform surface features are not in Preview 3; see [`docs/public/reference/supported-features.md`](../../docs/public/reference/supported-features.md).
+`Pocket` never means through-all; use a supported `Hole` or `Slot` for through removal. Bounded two-section [`Loft` and `Loft<Hollow>`](../../docs/public/firmament/loft.md) and WireForm [`Helix`](WireForm/helix.firmament) are admitted; general smooth/rail loft, arbitrary Boolean authoring, and freeform surface features are not in Preview 3; see [`docs/public/reference/supported-features.md`](../../docs/public/reference/supported-features.md).
## Ownership
diff --git a/fixtures/Canonical/WireForm/helix.firmament b/fixtures/Canonical/WireForm/helix.firmament
new file mode 100644
index 00000000..6df139c9
--- /dev/null
+++ b/fixtures/Canonical/WireForm/helix.firmament
@@ -0,0 +1,15 @@
+Model HelixWitness {
+ Units: mm
+ WireForm AxisSpring {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ Helix Winding {
+ Radius: 12mm
+ Turns: 8
+ Pitch: 5mm
+ Handedness: RightHanded
+ StartPhase: 0deg
+ }
+ }
+}