Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add minimal P1 semantic placement subset for Firmament
Yuechen Li528827aef4ff
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.csindex 6d507ff9..0e138678 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs@@ -1,4 +1,5 @@using System.Text;+using System.Linq;namespace Aetheris.Kernel.Firmament.Tests;@@ -209,6 +210,42 @@ public sealed class FirmamentBuildAndExportTests"subtract");}+ [Fact]+ public void Run_P1BlindHoleOnFaceSemanticExample_Writes_Default_Export_Artifact()+ {+ AssertExampleBuildAndExport(+ "testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmament",+ "p1_blind_hole_on_face_semantic.step",+ "blind_hole_tool",+ 1,+ "primitive",+ "cylinder");+ }++ [Fact]+ public void Run_P1FlangeRadialHoleSemanticExample_Writes_Default_Export_Artifact()+ {+ AssertExampleBuildAndExport(+ "testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament",+ "p1_flange_radial_hole_semantic.step",+ "radial_hole_tool",+ 1,+ "primitive",+ "cylinder");+ }++ [Fact]+ public void Semantic_Placement_Build_Is_Deterministic()+ {+ var fullSourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath("testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament");+ var first = FirmamentBuildAndExport.Run(fullSourcePath);+ var second = FirmamentBuildAndExport.Run(fullSourcePath);++ Assert.True(first.IsSuccess);+ Assert.True(second.IsSuccess);+ Assert.Equal(first.Value.Export.StepText, second.Value.Export.StepText);+ }+[Fact]public void Run_UnsupportedBoxWithCylinderHoleFixture_Fails_And_Does_Not_Write_Fallback_Export(){@@ -254,7 +291,7 @@ public sealed class FirmamentBuildAndExportTestsvar result = FirmamentBuildAndExport.Run(fullSourcePath);- Assert.True(result.IsSuccess);+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(d => d.Message)));Assert.Equal(fullSourcePath, result.Value.SourcePath);Assert.Equal(expectedOutputPath, result.Value.OutputPath);Assert.Equal(expectedFeatureId, result.Value.Export.ExportedFeatureId);diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.csindex d23253e4..f309f48d 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs@@ -33,6 +33,30 @@ public sealed class FirmamentPlacementValidationTestsAssert.True(result.Compilation.IsSuccess);}+ [Fact]+ public void Semantic_OnFace_Placement_For_Rib_Is_Valid()+ {+ var result = CompileFixture("testdata/firmament/examples/p1_bracket_rib_on_face_semantic.firmament");+ Assert.True(result.Compilation.IsSuccess, string.Join(Environment.NewLine, result.Compilation.Diagnostics.Select(d => d.Message)));+ }++ [Fact]+ public void Semantic_AroundAxis_And_RadialOffset_For_FlangeHole_Is_Valid()+ {+ var result = CompileFixture("testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament");+ Assert.True(result.Compilation.IsSuccess, string.Join(Environment.NewLine, result.Compilation.Diagnostics.Select(d => d.Message)));+ }++ [Fact]+ public void Unsupported_Placement_Semantic_Field_Is_Rejected_Loudly()+ {+ var result = CompileFixture("testdata/firmament/fixtures/p1-invalid-unsupported-placement-semantic.firmament");+ Assert.False(result.Compilation.IsSuccess);+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);+ Assert.Contains(FirmamentDiagnosticCodes.PlacementUnsupportedSemanticField.Value, diagnostic.Message, StringComparison.Ordinal);+ Assert.Contains("concentric_with", diagnostic.Message, StringComparison.Ordinal);+ }+[Fact]public void Primitive_With_Sphere_Surface_PlaceAnchor_Is_Valid(){diff --git a/Aetheris.Kernel.Firmament/Diagnostics/FirmamentDiagnosticCodes.cs b/Aetheris.Kernel.Firmament/Diagnostics/FirmamentDiagnosticCodes.csindex e9406243..beca80cf 100644--- a/Aetheris.Kernel.Firmament/Diagnostics/FirmamentDiagnosticCodes.cs+++ b/Aetheris.Kernel.Firmament/Diagnostics/FirmamentDiagnosticCodes.cs@@ -28,6 +28,8 @@ public static class FirmamentDiagnosticCodespublic static readonly FirmamentDiagnosticCode PlacementInvalidAnchorShape = new($"{FirmamentDiagnosticConventions.StructurePrefix}-0020");public static readonly FirmamentDiagnosticCode PlacementInvalidOffsetShape = new($"{FirmamentDiagnosticConventions.StructurePrefix}-0021");public static readonly FirmamentDiagnosticCode PlacementInvalidOffsetValue = new($"{FirmamentDiagnosticConventions.StructurePrefix}-0022");+ public static readonly FirmamentDiagnosticCode PlacementUnsupportedSemanticField = new($"{FirmamentDiagnosticConventions.StructurePrefix}-0023");+ public static readonly FirmamentDiagnosticCode PlacementInvalidSemanticCombination = new($"{FirmamentDiagnosticConventions.StructurePrefix}-0024");public static readonly FirmamentDiagnosticCode ReferenceDuplicateFeatureId = new($"{FirmamentDiagnosticConventions.ReferencePrefix}-0001");public static readonly FirmamentDiagnosticCode ReferenceUnknownFeatureId = new($"{FirmamentDiagnosticConventions.ReferencePrefix}-0002");diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.csindex 6c3b82c8..824e0b32 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs@@ -19,25 +19,70 @@ internal static class FirmamentPlacementResolver{if (primitive.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);- var anchorResult = ResolveAnchorPoint(primitive.Placement.On, featureBodies);- if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);+ var semanticAnchorResult = ResolveSemanticAnchorPoint(primitive.Placement, featureBodies);+ if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);++ var baseAnchorPoint = semanticAnchorResult.Value;+ if (!string.IsNullOrWhiteSpace(primitive.Placement.AroundAxis))+ {+ var axisResult = ResolveAxisFromSelector(primitive.Placement.AroundAxis!, featureBodies);+ if (!axisResult.IsSuccess) return KernelResult<Vector3D>.Failure(axisResult.Diagnostics);+ var radialOffset = primitive.Placement.RadialOffset ?? 0d;+ var angleDegrees = primitive.Placement.AngleDegrees ?? 0d;+ baseAnchorPoint = ResolveAroundAxisPoint(axisResult.Value, baseAnchorPoint, radialOffset, angleDegrees);+ }var o = primitive.Placement.Offset;return KernelResult<Vector3D>.Success(- (anchorResult.Value - Point3D.Origin)+ (baseAnchorPoint - Point3D.Origin)+ ResolvePrimitivePlacementLocalFrameCorrection(primitive)- + new Vector3D(o[0], o[1], o[2]));+ + ResolveOffset(o));}public static KernelResult<Vector3D> ResolvePlacementTranslation(FirmamentLoweredBoolean booleanOp, IReadOnlyDictionary<string, BrepBody> featureBodies){if (booleanOp.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);-- var anchorResult = ResolveAnchorPoint(booleanOp.Placement.On, featureBodies);- if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);+ var semanticAnchorResult = ResolveSemanticAnchorPoint(booleanOp.Placement, featureBodies);+ if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);+ var baseAnchorPoint = semanticAnchorResult.Value;+ if (!string.IsNullOrWhiteSpace(booleanOp.Placement.AroundAxis))+ {+ var axisResult = ResolveAxisFromSelector(booleanOp.Placement.AroundAxis!, featureBodies);+ if (!axisResult.IsSuccess) return KernelResult<Vector3D>.Failure(axisResult.Diagnostics);+ var radialOffset = booleanOp.Placement.RadialOffset ?? 0d;+ var angleDegrees = booleanOp.Placement.AngleDegrees ?? 0d;+ baseAnchorPoint = ResolveAroundAxisPoint(axisResult.Value, baseAnchorPoint, radialOffset, angleDegrees);+ }var o = booleanOp.Placement.Offset;- return KernelResult<Vector3D>.Success((anchorResult.Value - Point3D.Origin) + new Vector3D(o[0], o[1], o[2]));+ return KernelResult<Vector3D>.Success((baseAnchorPoint - Point3D.Origin) + ResolveOffset(o));+ }++ private static KernelResult<Point3D> ResolveSemanticAnchorPoint(FirmamentLoweredPlacement placement, IReadOnlyDictionary<string, BrepBody> featureBodies)+ {+ if (!string.IsNullOrWhiteSpace(placement.OnFace))+ {+ return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.OnFace!), featureBodies);+ }++ if (!string.IsNullOrWhiteSpace(placement.CenteredOn))+ {+ return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.CenteredOn!), featureBodies);+ }++ if (placement.On is not null)+ {+ return ResolveAnchorPoint(placement.On, featureBodies);+ }++ if (!string.IsNullOrWhiteSpace(placement.AroundAxis))+ {+ var axis = ResolveAxisFromSelector(placement.AroundAxis!, featureBodies);+ if (!axis.IsSuccess) return KernelResult<Point3D>.Failure(axis.Diagnostics);+ return KernelResult<Point3D>.Success(axis.Value.Origin);+ }++ return KernelResult<Point3D>.Success(Point3D.Origin);}private static Vector3D ResolvePrimitivePlacementLocalFrameCorrection(FirmamentLoweredPrimitive primitive)@@ -76,6 +121,94 @@ internal static class FirmamentPlacementResolver};}+ private static KernelResult<FirmamentPlacementAxis> ResolveAxisFromSelector(string selector, IReadOnlyDictionary<string, BrepBody> featureBodies)+ {+ var i = selector.IndexOf('.', StringComparison.Ordinal);+ if (i <= 0 || i >= selector.Length - 1) return FailureAxis($"Placement selector '{selector}' is not selector-shaped.");++ var featureId = selector[..i];+ var port = selector[(i + 1)..];+ if (!featureBodies.TryGetValue(featureId, out var body)) return FailureAxis($"Placement selector '{selector}' resolved empty at runtime.");++ var candidateFaces = body.Topology.Faces+ .Where(face => body.TryGetFaceSurfaceGeometry(face.Id, out var _) && true)+ .ToList();+ if (candidateFaces.Count == 0)+ {+ return FailureAxis($"Placement selector '{selector}' resolved empty face set at runtime.");+ }++ foreach (var face in candidateFaces)+ {+ body.TryGetFaceSurfaceGeometry(face.Id, out var surface);+ if (surface is null)+ {+ continue;+ }++ if (port == "side_face" && surface.Kind == SurfaceGeometryKind.Cylinder)+ {+ var c = surface.Cylinder!.Value;+ return KernelResult<FirmamentPlacementAxis>.Success(new FirmamentPlacementAxis(c.Origin, c.Axis.ToVector()));+ }++ if (port == "side_face" && surface.Kind == SurfaceGeometryKind.Cone)+ {+ var c = surface.Cone!.Value;+ return KernelResult<FirmamentPlacementAxis>.Success(new FirmamentPlacementAxis(c.Apex, c.Axis.ToVector()));+ }+ }++ return FailureAxis($"Placement selector '{selector}' cannot resolve an axis for P1 around-axis placement; expected cylindrical/conical side_face selector.");+ }++ private static Point3D ResolveAroundAxisPoint(FirmamentPlacementAxis axis, Point3D basePoint, double radialOffset, double angleDegrees)+ {+ if (!axis.Direction.TryNormalize(out var axisDir))+ {+ return basePoint;+ }+ var toBase = basePoint - axis.Origin;+ var projectedLength = toBase.Dot(axisDir);+ var onAxis = axis.Origin + (axisDir * projectedLength);++ var reference = new Vector3D(1d, 0d, 0d);+ if (!reference.TryNormalize(out var normalizedReference))+ {+ normalizedReference = new Vector3D(1d, 0d, 0d);+ }++ if (Math.Abs(normalizedReference.Dot(axisDir)) > 0.99d)+ {+ reference = new Vector3D(0d, 1d, 0d);+ }++ var radialUraw = reference - axisDir * reference.Dot(axisDir);+ if (!radialUraw.TryNormalize(out var radialU))+ {+ radialU = new Vector3D(1d, 0d, 0d);+ }++ var radialVraw = axisDir.Cross(radialU);+ if (!radialVraw.TryNormalize(out var radialV))+ {+ radialV = new Vector3D(0d, 1d, 0d);+ }+ var radians = angleDegrees * (Math.PI / 180d);+ var radial = (radialU * Math.Cos(radians) + radialV * Math.Sin(radians)) * radialOffset;+ return onAxis + radial;+ }++ private static Vector3D ResolveOffset(IReadOnlyList<double> offset)+ {+ if (offset.Count == 3)+ {+ return new Vector3D(offset[0], offset[1], offset[2]);+ }++ return Vector3D.Zero;+ }+private static KernelResult<Point3D> ResolveFaceAnchor(BrepBody body, string port){var facePoints = body.Topology.Faces@@ -237,4 +370,9 @@ internal static class FirmamentPlacementResolverprivate static KernelResult<Point3D> Failure(string message) =>KernelResult<Point3D>.Failure([new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error, $"[{FirmamentDiagnosticCodes.ValidationTargetSelectorResolvedEmpty.Value}] {message}", FirmamentDiagnosticConventions.Source)]);++ private static KernelResult<FirmamentPlacementAxis> FailureAxis(string message) =>+ KernelResult<FirmamentPlacementAxis>.Failure([new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error, $"[{FirmamentDiagnosticCodes.ValidationTargetSelectorResolvedEmpty.Value}] {message}", FirmamentDiagnosticConventions.Source)]);++ private readonly record struct FirmamentPlacementAxis(Point3D Origin, Vector3D Direction);}diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.csindex 8ada404f..0268967f 100644--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs@@ -116,13 +116,15 @@ internal static class FirmamentPrimitiveLowererFirmamentParsedPlacementSelectorAnchor selector => new FirmamentLoweredPlacementSelectorAnchor(selector.Selector),_ => null};-- if (loweredAnchor is null)- {- return null;- }-- return new FirmamentLoweredPlacement(loweredAnchor, placement.Offset);+ return new FirmamentLoweredPlacement(+ loweredAnchor,+ placement.Offset,+ placement.OnFace,+ placement.CenteredOn,+ placement.AroundAxis,+ placement.RadialOffset,+ placement.AngleDegrees,+ placement.UnknownFields);}private static FirmamentLoweredBoolean LowerBoolean(diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.csindex 87335a66..9884343a 100644--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs@@ -15,8 +15,14 @@ public sealed record FirmamentLoweredPrimitive(FirmamentLoweredPlacement? Placement);public sealed record FirmamentLoweredPlacement(- FirmamentLoweredPlacementAnchor On,- IReadOnlyList<double> Offset);+ FirmamentLoweredPlacementAnchor? On,+ IReadOnlyList<double> Offset,+ string? OnFace,+ string? CenteredOn,+ string? AroundAxis,+ double? RadialOffset,+ double? AngleDegrees,+ IReadOnlyList<string> UnknownFields);public abstract record FirmamentLoweredPlacementAnchor;diff --git a/Aetheris.Kernel.Firmament/ParsedModel/FirmamentParsedPlacement.cs b/Aetheris.Kernel.Firmament/ParsedModel/FirmamentParsedPlacement.csindex dcb28191..83beff51 100644--- a/Aetheris.Kernel.Firmament/ParsedModel/FirmamentParsedPlacement.cs+++ b/Aetheris.Kernel.Firmament/ParsedModel/FirmamentParsedPlacement.cs@@ -1,8 +1,14 @@namespace Aetheris.Kernel.Firmament.ParsedModel;public sealed record FirmamentParsedPlacement(- FirmamentParsedPlacementAnchor On,- IReadOnlyList<double> Offset);+ FirmamentParsedPlacementAnchor? On,+ IReadOnlyList<double> Offset,+ string? OnFace,+ string? CenteredOn,+ string? AroundAxis,+ double? RadialOffset,+ double? AngleDegrees,+ IReadOnlyList<string> UnknownFields);public abstract record FirmamentParsedPlacementAnchor;diff --git a/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs b/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.csindex 738284c5..94c05a47 100644--- a/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs+++ b/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs@@ -732,7 +732,7 @@ internal static class FirmamentTopLevelParserreturn null;}- var anchor = default(FirmamentParsedPlacementAnchor);+ FirmamentParsedPlacementAnchor? anchor = null;if (placeElement.TryGetProperty("on", out var onElement)){var onRaw = onElement.ToString();@@ -754,12 +754,23 @@ internal static class FirmamentTopLevelParser}}- if (anchor is null)- {- return null;- }+ var onFace = placeElement.TryGetProperty("on_face", out var onFaceElement) ? onFaceElement.ToString() : null;+ var centeredOn = placeElement.TryGetProperty("centered_on", out var centeredOnElement) ? centeredOnElement.ToString() : null;+ var aroundAxis = placeElement.TryGetProperty("around_axis", out var aroundAxisElement) ? aroundAxisElement.ToString() : null;+ var radialOffset = placeElement.TryGetProperty("radial_offset", out var radialOffsetElement) && radialOffsetElement.ValueKind == JsonValueKind.Number+ ? radialOffsetElement.GetDouble()+ : (double?)null;+ var angleDegrees = placeElement.TryGetProperty("angle_degrees", out var angleDegreesElement) && angleDegreesElement.ValueKind == JsonValueKind.Number+ ? angleDegreesElement.GetDouble()+ : (double?)null;+ var unknownFields = placeElement+ .EnumerateObject()+ .Select(p => p.Name)+ .Where(name => !KnownPlacementFields.Contains(name))+ .OrderBy(name => name, StringComparer.Ordinal)+ .ToArray();- return new FirmamentParsedPlacement(anchor, offset);+ return new FirmamentParsedPlacement(anchor, offset, onFace, centeredOn, aroundAxis, radialOffset, angleDegrees, unknownFields);}private static FirmamentParsedPlacement? ParsePlacementFromToon(FirmamentToonObjectEntry opEntry)@@ -778,7 +789,13 @@ internal static class FirmamentTopLevelParservar body = trimmed[1..^1].Trim();var pairs = SplitTopLevelCommaSeparated(body);string? on = null;+ string? onFace = null;+ string? centeredOn = null;+ string? aroundAxis = null;+ double? radialOffset = null;+ double? angleDegrees = null;var offset = new List<double>();+ var unknownFields = new List<string>();foreach (var pair in pairs){@@ -796,6 +813,39 @@ internal static class FirmamentTopLevelParseron = value;continue;}+ if (string.Equals(key, "on_face", StringComparison.Ordinal))+ {+ onFace = value;+ continue;+ }+ if (string.Equals(key, "centered_on", StringComparison.Ordinal))+ {+ centeredOn = value;+ continue;+ }+ if (string.Equals(key, "around_axis", StringComparison.Ordinal))+ {+ aroundAxis = value;+ continue;+ }+ if (string.Equals(key, "radial_offset", StringComparison.Ordinal))+ {+ if (TryParseNumeric(value, out var parsedRadialOffset))+ {+ radialOffset = parsedRadialOffset;+ }++ continue;+ }+ if (string.Equals(key, "angle_degrees", StringComparison.Ordinal))+ {+ if (TryParseNumeric(value, out var parsedAngleDegrees))+ {+ angleDegrees = parsedAngleDegrees;+ }++ continue;+ }if (string.Equals(key, "offset", StringComparison.Ordinal)&& value.StartsWith("[", StringComparison.Ordinal)@@ -809,21 +859,38 @@ internal static class FirmamentTopLevelParseroffset.Add(component);}}++ continue;+ }++ if (!KnownPlacementFields.Contains(key))+ {+ unknownFields.Add(key);}}- if (string.IsNullOrWhiteSpace(on))+ FirmamentParsedPlacementAnchor? anchor = null;+ if (!string.IsNullOrWhiteSpace(on)){- return null;+ anchor = string.Equals(on, "origin", StringComparison.Ordinal)+ ? (FirmamentParsedPlacementAnchor)new FirmamentParsedPlacementOriginAnchor()+ : new FirmamentParsedPlacementSelectorAnchor(on);}- var anchor = string.Equals(on, "origin", StringComparison.Ordinal)- ? (FirmamentParsedPlacementAnchor)new FirmamentParsedPlacementOriginAnchor()- : new FirmamentParsedPlacementSelectorAnchor(on);-- return new FirmamentParsedPlacement(anchor, offset);+ return new FirmamentParsedPlacement(anchor, offset, onFace, centeredOn, aroundAxis, radialOffset, angleDegrees, unknownFields.OrderBy(x => x, StringComparer.Ordinal).ToArray());}+ private static readonly HashSet<string> KnownPlacementFields = new(StringComparer.Ordinal)+ {+ "on",+ "offset",+ "on_face",+ "centered_on",+ "around_axis",+ "radial_offset",+ "angle_degrees"+ };+private static IReadOnlyList<string> SplitTopLevelCommaSeparated(string raw){var parts = new List<string>();diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.csindex f52b8f62..40153c30 100644--- a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs@@ -421,33 +421,48 @@ internal static class FirmamentBooleanRequiredFieldValidatorreturn KernelResult<bool>.Success(true);}- entry.RawFields.TryGetValue("place", out var placeRaw);- var hasOn = false;- var hasOffset = false;- TryReadPlacementFieldPresence(placeRaw ?? string.Empty, out hasOn, out hasOffset);-- if (!hasOn)+ if (entry.Placement is null){return KernelResult<bool>.Failure([CreateDiagnostic(FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Boolean op '{entry.OpName}' at index {opIndex} is missing required field 'place.on'.")]);+ $"Boolean op '{entry.OpName}' at index {opIndex} has invalid field 'place'; expected object-like placement block.")]);}- if (!hasOffset)+ if (entry.Placement.UnknownFields.Count > 0){return KernelResult<bool>.Failure([CreateDiagnostic(- FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Boolean op '{entry.OpName}' at index {opIndex} is missing required field 'place.offset'.")]);+ FirmamentDiagnosticCodes.PlacementUnsupportedSemanticField,+ $"Boolean op '{entry.OpName}' at index {opIndex} uses unsupported placement semantic field(s): {string.Join(", ", entry.Placement.UnknownFields.Select(f => $"'{f}'"))}.")]);}- if (entry.Placement is null)+ var usesSemantic = !string.IsNullOrWhiteSpace(entry.Placement.OnFace)+ || !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)+ || !string.IsNullOrWhiteSpace(entry.Placement.AroundAxis)+ || entry.Placement.RadialOffset is not null+ || entry.Placement.AngleDegrees is not null;++ if (!usesSemantic && entry.Placement.On is null){return KernelResult<bool>.Failure([CreateDiagnostic(FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Boolean op '{entry.OpName}' at index {opIndex} has invalid field 'place'; expected object-like placement block with required fields 'on' and 'offset'.")]);+ $"Boolean op '{entry.OpName}' at index {opIndex} is missing required field 'place.on'.")]);+ }++ if (!usesSemantic)+ {+ entry.RawFields.TryGetValue("place", out var placeRaw);+ var hasOffset = false;+ _ = TryReadPlacementFieldPresence(placeRaw ?? string.Empty, out _, out hasOffset);+ if (!hasOffset)+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementMissingRequiredField,+ $"Boolean op '{entry.OpName}' at index {opIndex} is missing required field 'place.offset'.")]);+ }}if (entry.Placement.On is FirmamentParsedPlacementSelectorAnchor selectorAnchor)@@ -461,7 +476,7 @@ internal static class FirmamentBooleanRequiredFieldValidator$"Boolean op '{entry.OpName}' at index {opIndex} has invalid placement anchor in field 'place.on'; expected 'origin' or selector-shaped token 'feature.port'.")]);}}- else if (entry.Placement.On is not FirmamentParsedPlacementOriginAnchor)+ else if (entry.Placement.On is not null && entry.Placement.On is not FirmamentParsedPlacementOriginAnchor){return KernelResult<bool>.Failure([CreateDiagnostic(@@ -469,6 +484,22 @@ internal static class FirmamentBooleanRequiredFieldValidator$"Boolean op '{entry.OpName}' at index {opIndex} has invalid placement anchor in field 'place.on'; expected 'origin' or selector-shaped token 'feature.port'.")]);}+ var semanticSelectorError = ValidateSemanticSelectorField(entry.Placement.OnFace, "place.on_face", entry, opIndex)+ ?? ValidateSemanticSelectorField(entry.Placement.CenteredOn, "place.centered_on", entry, opIndex)+ ?? ValidateSemanticSelectorField(entry.Placement.AroundAxis, "place.around_axis", entry, opIndex);+ if (semanticSelectorError is not null)+ {+ return KernelResult<bool>.Failure([semanticSelectorError]);+ }++ if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis))+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,+ $"Boolean op '{entry.OpName}' at index {opIndex} has invalid placement semantics; 'place.radial_offset' requires 'place.around_axis'.")]);+ }+if (entry.RawFields.TryGetValue("place", out var placeRawForOffset)&& TryReadOffsetRawTokens(placeRawForOffset, out var offsetTokens)&& offsetTokens.Count == 3@@ -480,7 +511,7 @@ internal static class FirmamentBooleanRequiredFieldValidator$"Boolean op '{entry.OpName}' at index {opIndex} has invalid field 'place.offset' value; all components must be numeric.")]);}- if (entry.Placement.Offset.Count != 3)+ if (entry.Placement.Offset.Count > 0 && entry.Placement.Offset.Count != 3){return KernelResult<bool>.Failure([CreateDiagnostic(@@ -491,6 +522,24 @@ internal static class FirmamentBooleanRequiredFieldValidatorreturn KernelResult<bool>.Success(true);}+ private static KernelDiagnostic? ValidateSemanticSelectorField(string? selector, string fieldName, FirmamentParsedOpEntry entry, int opIndex)+ {+ if (string.IsNullOrWhiteSpace(selector))+ {+ return null;+ }++ if (!FirmamentValidationTargetClassifier.TryClassify(selector, out var shape)+ || shape != FirmamentValidationTargetShape.SelectorShaped)+ {+ return CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidAnchorShape,+ $"Boolean op '{entry.OpName}' at index {opIndex} has invalid placement selector in field '{fieldName}'; expected selector-shaped token 'feature.port'.");+ }++ return null;+ }+private static bool TryReadPlacementFieldPresence(string placeRaw, out bool hasOn, out bool hasOffset){hasOn = false;diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.csindex 174fce4a..997994af 100644--- a/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs@@ -150,21 +150,55 @@ internal static class FirmamentDocumentCoherenceValidator{diagnostic = null;- if (entry.Placement?.On is not FirmamentParsedPlacementSelectorAnchor selectorAnchor)+ var selectorAnchor = entry.Placement?.On as FirmamentParsedPlacementSelectorAnchor;++ if (selectorAnchor is not null){- return;+ TryValidateSelectorReference(+ selectorAnchor.Selector,+ featureIds,+ featureKindsById,+ $"Primitive op '{entry.OpName}' at index {index}",+ "place.on",+ out _,+ out _,+ out _,+ out diagnostic);+ if (diagnostic is not null)+ {+ return;+ }+ }++ diagnostic = ValidateSemanticPlacementSelector(entry.Placement?.OnFace, featureIds, featureKindsById, entry, index, "place.on_face")+ ?? ValidateSemanticPlacementSelector(entry.Placement?.CenteredOn, featureIds, featureKindsById, entry, index, "place.centered_on")+ ?? ValidateSemanticPlacementSelector(entry.Placement?.AroundAxis, featureIds, featureKindsById, entry, index, "place.around_axis");+ }++ private static KernelDiagnostic? ValidateSemanticPlacementSelector(+ string? selector,+ HashSet<string> featureIds,+ IReadOnlyDictionary<string, FirmamentKnownOpKind> featureKindsById,+ FirmamentParsedOpEntry entry,+ int index,+ string fieldName)+ {+ if (string.IsNullOrWhiteSpace(selector))+ {+ return null;}TryValidateSelectorReference(- selectorAnchor.Selector,+ selector,featureIds,featureKindsById,$"Primitive op '{entry.OpName}' at index {index}",- "place.on",+ fieldName,out _,out _,out _,- out diagnostic);+ out var diagnostic);+ return diagnostic;}private static bool TryValidateSelectorReference(diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.csindex 07c8e091..d68bc15e 100644--- a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs@@ -219,32 +219,47 @@ internal static class FirmamentPrimitiveRequiredFieldValidator}entry.RawFields.TryGetValue("place", out var placeRaw);- var hasOn = false;- var hasOffset = false;- TryReadPlacementFieldPresence(placeRaw ?? string.Empty, out hasOn, out hasOffset);-- if (!hasOn)+ if (entry.Placement is null){return KernelResult<bool>.Failure([CreateDiagnostic(FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Primitive op '{entry.OpName}' at index {opIndex} is missing required field 'place.on'.")]);+ $"Primitive op '{entry.OpName}' at index {opIndex} has invalid field 'place'; expected object-like placement block.")]);}- if (!hasOffset)+ if (entry.Placement.UnknownFields.Count > 0){return KernelResult<bool>.Failure([CreateDiagnostic(- FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Primitive op '{entry.OpName}' at index {opIndex} is missing required field 'place.offset'.")]);+ FirmamentDiagnosticCodes.PlacementUnsupportedSemanticField,+ $"Primitive op '{entry.OpName}' at index {opIndex} uses unsupported placement semantic field(s): {string.Join(", ", entry.Placement.UnknownFields.Select(f => $"'{f}'"))}.")]);}- if (entry.Placement is null)+ var usesSemantic = !string.IsNullOrWhiteSpace(entry.Placement.OnFace)+ || !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)+ || !string.IsNullOrWhiteSpace(entry.Placement.AroundAxis)+ || entry.Placement.RadialOffset is not null+ || entry.Placement.AngleDegrees is not null;++ if (!usesSemantic && entry.Placement.On is null){return KernelResult<bool>.Failure([CreateDiagnostic(FirmamentDiagnosticCodes.PlacementMissingRequiredField,- $"Primitive op '{entry.OpName}' at index {opIndex} has invalid field 'place'; expected object-like placement block with required fields 'on' and 'offset'.")]);+ $"Primitive op '{entry.OpName}' at index {opIndex} is missing required field 'place.on'.")]);+ }++ if (!usesSemantic)+ {+ var hasOffset = false;+ _ = TryReadPlacementFieldPresence(placeRaw ?? string.Empty, out _, out hasOffset);+ if (!hasOffset)+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementMissingRequiredField,+ $"Primitive op '{entry.OpName}' at index {opIndex} is missing required field 'place.offset'.")]);+ }}if (entry.Placement.On is FirmamentParsedPlacementSelectorAnchor selectorAnchor)@@ -258,7 +273,7 @@ internal static class FirmamentPrimitiveRequiredFieldValidator$"Primitive op '{entry.OpName}' at index {opIndex} has invalid placement anchor in field 'place.on'; expected 'origin' or selector-shaped token 'feature.port'.")]);}}- else if (entry.Placement.On is not FirmamentParsedPlacementOriginAnchor)+ else if (entry.Placement.On is not null && entry.Placement.On is not FirmamentParsedPlacementOriginAnchor){return KernelResult<bool>.Failure([CreateDiagnostic(@@ -266,6 +281,22 @@ internal static class FirmamentPrimitiveRequiredFieldValidator$"Primitive op '{entry.OpName}' at index {opIndex} has invalid placement anchor in field 'place.on'; expected 'origin' or selector-shaped token 'feature.port'.")]);}+ var semanticSelectorError = ValidateSemanticSelectorField(entry.Placement.OnFace, "place.on_face", entry, opIndex)+ ?? ValidateSemanticSelectorField(entry.Placement.CenteredOn, "place.centered_on", entry, opIndex)+ ?? ValidateSemanticSelectorField(entry.Placement.AroundAxis, "place.around_axis", entry, opIndex);+ if (semanticSelectorError is not null)+ {+ return KernelResult<bool>.Failure([semanticSelectorError]);+ }++ if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis))+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,+ $"Primitive op '{entry.OpName}' at index {opIndex} has invalid placement semantics; 'place.radial_offset' requires 'place.around_axis'.")]);+ }+if (entry.RawFields.TryGetValue("place", out var placeRawForOffset)&& TryReadOffsetRawTokens(placeRawForOffset, out var offsetTokens)&& offsetTokens.Count == 3@@ -277,7 +308,7 @@ internal static class FirmamentPrimitiveRequiredFieldValidator$"Primitive op '{entry.OpName}' at index {opIndex} has invalid field 'place.offset' value; all components must be numeric.")]);}- if (entry.Placement.Offset.Count != 3)+ if (entry.Placement.Offset.Count > 0 && entry.Placement.Offset.Count != 3){return KernelResult<bool>.Failure([CreateDiagnostic(@@ -288,6 +319,24 @@ internal static class FirmamentPrimitiveRequiredFieldValidatorreturn KernelResult<bool>.Success(true);}+ private static KernelDiagnostic? ValidateSemanticSelectorField(string? selector, string fieldName, FirmamentParsedOpEntry entry, int opIndex)+ {+ if (string.IsNullOrWhiteSpace(selector))+ {+ return null;+ }++ if (!FirmamentValidationTargetClassifier.TryClassify(selector, out var shape)+ || shape != FirmamentValidationTargetShape.SelectorShaped)+ {+ return CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidAnchorShape,+ $"Primitive op '{entry.OpName}' at index {opIndex} has invalid placement selector in field '{fieldName}'; expected selector-shaped token 'feature.port'.");+ }++ return null;+ }+private static bool TryReadPlacementFieldPresence(string placeRaw, out bool hasOn, out bool hasOffset){hasOn = false;diff --git a/docs/firmament-language-shape.md b/docs/firmament-language-shape.mdindex 3637a2ee..783a18e4 100644--- a/docs/firmament-language-shape.md+++ b/docs/firmament-language-shape.md@@ -182,6 +182,44 @@ Notes:---+# Placement Shape (P1 subset)++Placement remains optional. When present, use a small explicit `place` object.++Legacy anchor placement:++```+place:+ on: origin+ offset[3]:+ 0+ 0+ 0+```++Semantic placement subset (P1):++```+place:+ on_face: base.top_face+ centered_on: flange.top_face+ around_axis: flange.side_face+ radial_offset: 20+ angle_degrees: 30+ offset[3]:+ 0+ 0+ -12+```++Rules:+- Supported semantic fields are exactly: `on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`.+- `radial_offset` requires `around_axis`.+- Unknown placement semantic keys are rejected.+- This is a minimal ergonomics subset; it is **not** a general frame/constraint language.++---+# Validation OperationsValidation operations do not create geometry.diff --git a/docs/firmament-overview.md b/docs/firmament-overview.mdindex 6afcc0c6..9796542b 100644--- a/docs/firmament-overview.md+++ b/docs/firmament-overview.md@@ -15,7 +15,7 @@ Firmament currently supports these source-level concepts:- primitive features: `box`, `cylinder`, `sphere`- boolean features: `add`, `subtract`, `intersect`- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`-- placement blocks with `place.on` and `offset[3]`+- placement blocks with legacy `place.on` + `offset[3]` and minimal P1 semantic placement (`on_face`, `centered_on`, `around_axis`, `radial_offset`)- selector-shaped references rooted at a source feature id- optional schema blocks for `cnc`, `additive`, and `injection_molded`- first schema-aware CNC DFM validation for `minimum_tool_radius` on subtract-with-cylinder inputs@@ -49,13 +49,16 @@ Validation ops check feature existence, selector selectability, and manifold exp### Placement-Placement currently supports an anchor plus a translation offset:+Placement currently supports two small models:- `place.on: origin`- `place.on: feature_id.port`- `offset[3]` numeric translation+- `place.on_face: feature_id.port`+- `place.centered_on: feature_id.port`+- `place.around_axis: feature_id.port` (+ optional `place.radial_offset` and `place.angle_degrees`)-This is intentionally narrow. Arbitrary rotations and generalized transform stacks are not part of the current language surface.+This is intentionally narrow. It lowers deterministically into selector anchor extraction + axis/radial translation and does not introduce a general frame system or constraint solver.### Schemadiff --git a/testdata/firmament/examples/README.md b/testdata/firmament/examples/README.mdindex 3ce0b6e3..4c03a0aa 100644--- a/testdata/firmament/examples/README.md+++ b/testdata/firmament/examples/README.md@@ -22,6 +22,9 @@ Other combinations may fail and are intentionally not supported yet.- `boolean_cylinder_cone_holes_basic.firmament` — canonical sequential safe composition case for `box → subtract cylinder → subtract cone`; helper export path: `testdata/firmament/exports/boolean_cylinder_cone_holes_basic.step`.- `boolean_box_sphere_cavity_basic.firmament` — narrow supported `subtract(box, sphere)` cavity case only: the sphere must remain strictly contained and non-tangent so the result can be reconstructed as one outer shell plus one inner spherical shell; helper export path: `testdata/firmament/exports/boolean_box_sphere_cavity_basic.step`.- `placed_primitive.firmament` — selector-based placement using `place.on` and `offset[3]`; helper export path: `testdata/firmament/exports/placed_primitive.step`.+- `p1_blind_hole_on_face_semantic.firmament` — minimal semantic placement subset example using `place.on_face` for a blind-hole tool placement.+- `p1_flange_radial_hole_semantic.firmament` — minimal semantic placement subset example using `place.around_axis` + `place.radial_offset` for flange radial hole placement.+- `p1_bracket_rib_on_face_semantic.firmament` — minimal semantic placement subset example using `place.on_face` for bracket rib authoring ergonomics.- `schema_box_basic.firmament` — minimal schema-present export example showing schema presence without changing export body semantics; helper export path: `testdata/firmament/exports/schema_box_basic.step`.Unsupported boolean requests are tracked as fixtures/tests, not presented in this working example pack. The supported safe subtract family remains narrow and explicit: `subtract(box, cylinder)` and `subtract(box, cone)` still require a Z-aligned tool, full span through the current box shell, non-degenerate boundary circles for cones, and strict in-bounds clearance with no tangent/grazing contact. Sequential composition is limited to repeated document-order subtracts from that same safe family only: `box → subtract cylinder/cone → subtract cylinder/cone`, while the intermediate result must stay representable as one outer box shell plus non-interfering analytic through-holes. This is not general multi-feature boolean support. Box+cylinder `add`, box+cylinder `intersect`, rotated cylinders, partial-depth cuts, tangent/grazing cases, outside-footprint cuts, interfering multi-hole layouts, and unsupported subtract orderings remain unsupported. Box+cone `add`, box+cone `intersect`, tilted cones, partial-depth cone cuts, tangent/grazing cone cuts, apex-inside cases, outside-footprint cone cuts, and unsupported mixed-ordering requests remain unsupported. Box+sphere support is still narrow and truth-first: only `subtract(box, sphere)` with a strictly contained, non-tangent, fully enclosed cavity is supported, reconstructed via one outer shell plus one inner spherical shell. `add(box, sphere)`, `intersect(box, sphere)`, tangent cavity requests, and partially outside sphere requests remain unsupported. Box+torus booleans are currently unsupported in every audited form: `subtract(box, torus)`, `add(box, torus)`, and `intersect(box, torus)` all fail the real kernel boundary for centered, offset, fully contained, face-intersecting, and outside-footprint torus placements, so no box+torus example is included here. These files are intended to stay minimal, readable, and aligned with the implemented language surface. Export artifacts are kept separately under `testdata/firmament/exports/` so examples remain source-only and demo outputs stay easy to find.diff --git a/testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmament b/testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmamentnew file mode 100644index 00000000..ad45ebad--- /dev/null+++ b/testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmament@@ -0,0 +1,27 @@+firmament:+ version: 1++model:+ name: p1_blind_hole_on_face_semantic+ units: mm++ops[2]:+ -+ op: box+ id: base+ size[3]:+ 40+ 40+ 12++ -+ op: cylinder+ id: blind_hole_tool+ radius: 4+ height: 8+ place:+ on_face: base.top_face+ offset[3]:+ 0+ 0+ -8diff --git a/testdata/firmament/examples/p1_bracket_rib_on_face_semantic.firmament b/testdata/firmament/examples/p1_bracket_rib_on_face_semantic.firmamentnew file mode 100644index 00000000..d264c9cc--- /dev/null+++ b/testdata/firmament/examples/p1_bracket_rib_on_face_semantic.firmament@@ -0,0 +1,29 @@+firmament:+ version: 1++model:+ name: p1_bracket_rib_on_face_semantic+ units: mm++ops[2]:+ -+ op: box+ id: bracket+ size[3]:+ 60+ 20+ 8++ -+ op: box+ id: rib+ size[3]:+ 30+ 6+ 24+ place:+ on_face: bracket.top_face+ offset[3]:+ 15+ 7+ 0diff --git a/testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament b/testdata/firmament/examples/p1_flange_radial_hole_semantic.firmamentnew file mode 100644index 00000000..2868d9d8--- /dev/null+++ b/testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament@@ -0,0 +1,28 @@+firmament:+ version: 1++model:+ name: p1_flange_radial_hole_semantic+ units: mm++ops[2]:+ -+ op: cylinder+ id: flange+ radius: 36+ height: 12++ -+ op: cylinder+ id: radial_hole_tool+ radius: 3+ height: 12+ place:+ on_face: flange.top_face+ around_axis: flange.side_face+ radial_offset: 20+ angle_degrees: 30+ offset[3]:+ 0+ 0+ -12diff --git a/testdata/firmament/fixtures/p1-invalid-unsupported-placement-semantic.firmament b/testdata/firmament/fixtures/p1-invalid-unsupported-placement-semantic.firmamentnew file mode 100644index 00000000..ed786d51--- /dev/null+++ b/testdata/firmament/fixtures/p1-invalid-unsupported-placement-semantic.firmament@@ -0,0 +1,21 @@+firmament:+ version: 1++model:+ name: p1_invalid_unsupported_placement_semantic+ units: mm++ops[1]:+ -+ op: box+ id: base+ size[3]:+ 10+ 10+ 10+ place:+ concentric_with: prior.axis+ offset[3]:+ 0+ 0+ 0