Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Stabilize fixture corpus expectations after HOLE-X1

Yuechen Li43e15bf529a4
diff --git a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
index caebb0f6..9a7d6155 100644
--- a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
+++ b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
@@ -126,22 +126,23 @@ public sealed class FirmamentFixtureCorpusTests
Assert.Contains(fixtures, p => p.EndsWith("PMI/future/pmi-datum-flatness-position-v2.valid.firmfixture", StringComparison.Ordinal));
Assert.Contains(fixtures, p => p.EndsWith("PMI/future/pmi-material-surface-finish-v2.valid.firmfixture", StringComparison.Ordinal));
Assert.Contains(fixtures, p => p.EndsWith("PMI/invalid/pmi-raw-brep-id-target-v2.invalid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("Decompile/ctc-01-candidate-v2.firmfixture", StringComparison.Ordinal));
foreach (var path in fixtures)
{
var fixture = LoadMetadata(path);
foreach (var key in RequiredMetadata) Assert.True(fixture.ContainsKey(key), $"{path} missing {key}");
Assert.Equal("FirmamentV2", fixture["syntax-version"]);
- Assert.Contains(fixture["validity"], new[] { "valid", "invalid" });
- Assert.Contains(fixture["implementation"], new[] { "not-implemented", "rejected", "parser-backed" });
- if (fixture["implementation"] != "parser-backed") Assert.True(fixture.ContainsKey("expected-diagnostic"), $"{path} missing expected-diagnostic");
+ Assert.Contains(fixture["validity"], new[] { "valid", "invalid", "semantic-candidate" });
+ Assert.Contains(fixture["implementation"], new[] { "not-implemented", "rejected", "parser-backed", "design-only-not-implemented" });
+ if (fixture["implementation"] != "parser-backed" && fixture["validity"] != "semantic-candidate") Assert.True(fixture.ContainsKey("expected-diagnostic"), $"{path} missing expected-diagnostic");
}
}
[Fact]
public void FirmamentV2DesignFixtures_AreNotTreatedAsV1ParseFailures()
{
- foreach (var path in DiscoverV2Fixtures())
+ foreach (var path in DiscoverV2TraceFixtures())
{
using var doc = Trace(path);
var root = doc.RootElement;
@@ -437,6 +438,8 @@ public sealed class FirmamentFixtureCorpusTests
private static string[] DiscoverV2Fixtures() => Directory.EnumerateFiles(V2CorpusRoot, "*.firmfixture", SearchOption.AllDirectories).Select(p => p.Replace('\\', '/')).Order(StringComparer.Ordinal).ToArray();
+ private static string[] DiscoverV2TraceFixtures() => DiscoverV2Fixtures().Where(path => path.EndsWith(".valid.firmfixture", StringComparison.Ordinal) || path.EndsWith(".invalid.firmfixture", StringComparison.Ordinal)).ToArray();
+
private static JsonDocument Trace(string fixturePath, params string[] extraArgs)
{
var stdout = new StringWriter(); var stderr = new StringWriter();
diff --git a/Aetheris.Kernel.Core.Tests/Air/AirHoleFeatureTests.cs b/Aetheris.Kernel.Core.Tests/Air/AirHoleFeatureTests.cs
new file mode 100644
index 00000000..5476a69c
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Air/AirHoleFeatureTests.cs
@@ -0,0 +1,89 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Tests.Air;
+
+public sealed class AirHoleFeatureTests
+{
+ [Fact]
+ public void SimpleShaftHole_PreservesSemanticIntentBeforeLowering()
+ {
+ var feature = ValidFeature(new AirHoleEndCondition.ThroughAll());
+
+ Assert.True(feature.IsValid);
+ Assert.Equal("mount-hole", feature.Name);
+ Assert.Equal("hole-001", feature.FeatureId);
+ Assert.Equal("body-main", feature.TargetBodyId);
+ Assert.Equal("top", feature.Placement.EntryFaceName);
+ Assert.Equal(1.25, feature.Placement.U);
+ Assert.Equal(-2.5, feature.Placement.V);
+ Assert.True(feature.Axis.DefaultedFromEntryFaceNormal);
+ Assert.Equal(1, feature.Axis.Direction.Z, 12);
+ Assert.Equal(6, feature.Shaft.Diameter);
+ Assert.Equal(3, feature.Shaft.Radius);
+ Assert.IsType<AirHoleEndCondition.ThroughAll>(feature.EndCondition);
+ Assert.Equal("HOLE-X1", feature.Provenance.Milestone);
+ Assert.Equal("Semantic hole AIR scaffold", feature.Provenance.SourceKind);
+ }
+
+ [Fact]
+ public void SimpleShaftHole_DepthEndConditionIsPreserved()
+ {
+ var feature = ValidFeature(new AirHoleEndCondition.Depth(4.5));
+
+ var depth = Assert.IsType<AirHoleEndCondition.Depth>(feature.EndCondition);
+ Assert.Equal(AirHoleEndConditionKind.Depth, depth.Kind);
+ Assert.Equal(4.5, depth.Value);
+ Assert.DoesNotContain(feature.Diagnostics, d => d.Severity == AirDiagnosticSeverity.Error);
+ }
+
+ [Fact]
+ public void SimpleShaftHole_LoweringCandidateKeepsSemanticFeatureNotAnonymousCylinderCut()
+ {
+ var feature = ValidFeature(new AirHoleEndCondition.ThroughAll());
+
+ var plan = feature.CreateSimpleShaftLoweringPlan();
+
+ Assert.Same(feature, plan.Feature);
+ Assert.Equal(AirHoleLoweringRouteKind.SimpleShaftProfileStackCandidate, plan.RouteKind);
+ Assert.False(plan.Executed);
+ Assert.Contains("semantic-intent", plan.Recommendation);
+ Assert.DoesNotContain("CylinderCut", plan.RouteKind.ToString(), StringComparison.OrdinalIgnoreCase);
+ }
+
+ [Fact]
+ public void SimpleShaftHole_InvalidPlacementDiameterAndDepthEmitDeterministicDiagnostics()
+ {
+ var feature = AirHoleFeature.CreateSimpleShaft(
+ "bad-hole",
+ "hole-bad",
+ "body-main",
+ new AirFaceLocalHolePlacement("", double.NaN, 0, ""),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(0, 0, 1)), true),
+ new AirHoleShaft(0),
+ new AirHoleEndCondition.Depth(-1));
+
+ Assert.False(feature.IsValid);
+ Assert.Equal(new[]
+ {
+ "hole-x1-entry-face-required",
+ "hole-x1-placement-frame-required",
+ "hole-x1-placement-center-invalid",
+ "hole-x1-diameter-invalid",
+ "hole-x1-depth-invalid"
+ }, feature.Diagnostics.Select(d => d.Code).ToArray());
+
+ var plan = feature.CreateSimpleShaftLoweringPlan();
+ Assert.Equal(AirHoleLoweringRouteKind.NotLowered, plan.RouteKind);
+ Assert.False(plan.Executed);
+ }
+
+ private static AirHoleFeature ValidFeature(AirHoleEndCondition endCondition) => AirHoleFeature.CreateSimpleShaft(
+ "mount-hole",
+ "hole-001",
+ "body-main",
+ new AirFaceLocalHolePlacement("top", 1.25, -2.5, "face(top):u=+X,v=+Y", "face(top)"),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(0, 0, 1)), true),
+ new AirHoleShaft(6),
+ endCondition);
+}
diff --git a/Aetheris.Kernel.Core/Air/AirHoleFeature.cs b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
new file mode 100644
index 00000000..18a8e5dd
--- /dev/null
+++ b/Aetheris.Kernel.Core/Air/AirHoleFeature.cs
@@ -0,0 +1,110 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Air;
+
+internal enum AirHoleEndConditionKind { ThroughAll, Depth }
+internal enum AirHoleLoweringRouteKind { NotLowered, SimpleShaftProfileStackCandidate }
+
+internal sealed record AirHoleFeature(
+ string Name,
+ string FeatureId,
+ string? TargetBodyId,
+ AirFaceLocalHolePlacement Placement,
+ AirHoleAxis Axis,
+ AirHoleShaft Shaft,
+ AirHoleEndCondition EndCondition,
+ AirProvenance Provenance,
+ IReadOnlyList<AirDiagnostic> Diagnostics)
+{
+ public const string Milestone = "HOLE-X1";
+ public const string UnsupportedCounterboreDiagnostic = "hole-x1-counterbore-deferred";
+ public const string UnsupportedCountersinkDiagnostic = "hole-x1-countersink-deferred";
+ public const string UnsupportedThreadDiagnostic = "hole-x1-thread-deferred";
+
+ public bool IsValid => Diagnostics.All(d => d.Severity != AirDiagnosticSeverity.Error);
+
+ public static AirHoleFeature CreateSimpleShaft(
+ string name,
+ string featureId,
+ string? targetBodyId,
+ AirFaceLocalHolePlacement placement,
+ AirHoleAxis axis,
+ AirHoleShaft shaft,
+ AirHoleEndCondition endCondition,
+ AirProvenance? provenance = null)
+ {
+ var diagnostics = Validate(name, featureId, placement, axis, shaft, endCondition).ToArray();
+ return new AirHoleFeature(
+ name,
+ featureId,
+ targetBodyId,
+ placement,
+ axis,
+ shaft,
+ endCondition,
+ provenance ?? DefaultProvenance(name, featureId),
+ diagnostics);
+ }
+
+ public AirHoleLoweringPlan CreateSimpleShaftLoweringPlan()
+ {
+ if (!IsValid)
+ {
+ return new AirHoleLoweringPlan(this, AirHoleLoweringRouteKind.NotLowered, false, "semantic-hole-invalid-before-lowering", Diagnostics);
+ }
+
+ return new AirHoleLoweringPlan(
+ this,
+ AirHoleLoweringRouteKind.SimpleShaftProfileStackCandidate,
+ false,
+ "hole-x1-preserves-semantic-intent; executable-profile-stack-lowering-deferred",
+ [new AirDiagnostic("hole-x1-simple-shaft-lowering-deferred", AirDiagnosticSeverity.Info, "HOLE-X1 records a deterministic simple shaft lowering candidate but does not execute BRep/profile-stack materialization.")]);
+ }
+
+ private static AirProvenance DefaultProvenance(string name, string featureId) => new(
+ Milestone,
+ "Semantic hole AIR scaffold",
+ name,
+ featureId,
+ nameof(AirHoleFeature),
+ AirSelectionClass.None,
+ AirRuleKind.None,
+ "authored/semantic-hole-intent",
+ true,
+ ["Simple shaft hole only; throughAll and fixed depth end conditions are represented before lower geometry."]);
+
+ private static IEnumerable<AirDiagnostic> Validate(string name, string featureId, AirFaceLocalHolePlacement placement, AirHoleAxis axis, AirHoleShaft shaft, AirHoleEndCondition endCondition)
+ {
+ if (string.IsNullOrWhiteSpace(name)) yield return Error("hole-x1-name-required", "Hole feature name is required.");
+ if (string.IsNullOrWhiteSpace(featureId)) yield return Error("hole-x1-feature-id-required", "Hole feature id is required.");
+ if (string.IsNullOrWhiteSpace(placement.EntryFaceName)) yield return Error("hole-x1-entry-face-required", "Face-local hole placement requires an entry face.");
+ if (string.IsNullOrWhiteSpace(placement.FrameConvention)) yield return Error("hole-x1-placement-frame-required", "Face-local hole placement requires a frame convention.");
+ if (!IsFinite(placement.U) || !IsFinite(placement.V)) yield return Error("hole-x1-placement-center-invalid", "Face-local hole center coordinates must be finite.");
+ if (!IsFinite(axis.Direction.X) || !IsFinite(axis.Direction.Y) || !IsFinite(axis.Direction.Z)) yield return Error("hole-x1-axis-invalid", "Hole axis direction must be finite.");
+ if (!IsFinite(shaft.Diameter) || shaft.Diameter <= 0d) yield return Error("hole-x1-diameter-invalid", "Simple shaft hole diameter must be greater than zero.");
+ if (endCondition is AirHoleEndCondition.Depth depth && (!IsFinite(depth.Value) || depth.Value <= 0d)) yield return Error("hole-x1-depth-invalid", "Depth end condition must be greater than zero.");
+ }
+
+ private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+ private static AirDiagnostic Error(string code, string message) => new(code, AirDiagnosticSeverity.Error, message);
+}
+
+internal sealed record AirFaceLocalHolePlacement(string EntryFaceName, double U, double V, string FrameConvention, string? StableFaceSelector = null);
+internal sealed record AirHoleAxis(Direction3D Direction, bool DefaultedFromEntryFaceNormal);
+internal sealed record AirHoleShaft(double Diameter)
+{
+ public double Radius => Diameter / 2d;
+}
+
+internal abstract record AirHoleEndCondition(AirHoleEndConditionKind Kind)
+{
+ public sealed record ThroughAll() : AirHoleEndCondition(AirHoleEndConditionKind.ThroughAll);
+ public sealed record Depth(double Value) : AirHoleEndCondition(AirHoleEndConditionKind.Depth);
+}
+
+internal sealed record AirHoleLoweringPlan(
+ AirHoleFeature Feature,
+ AirHoleLoweringRouteKind RouteKind,
+ bool Executed,
+ string Recommendation,
+ IReadOnlyList<AirDiagnostic> Diagnostics);
diff --git a/docs/implementation/hole-x1-semantic-hole-feature.md b/docs/implementation/hole-x1-semantic-hole-feature.md
new file mode 100644
index 00000000..8d155f53
--- /dev/null
+++ b/docs/implementation/hole-x1-semantic-hole-feature.md
@@ -0,0 +1,35 @@
+# HOLE-X1 semantic hole feature scaffold
+
+HOLE-X1 adds a production AIR-owned semantic scaffold for simple shaft holes. A hole is represented as manufacturing/authoring intent before any profile stack, cylinder, trim loop, BRep face, or safe boolean lowering detail is chosen.
+
+## Supported in HOLE-X1
+
+- A semantic `AirHoleFeature` with stable feature name and id.
+- Optional target body id.
+- Face-local placement on a stable planar entry face selector/name.
+- Face-local center coordinates (`U`, `V`) and an explicit frame convention.
+- Axis direction, including whether it defaulted from the entry-face normal.
+- Simple shaft diameter and derived radius.
+- End conditions:
+ - `throughAll`.
+ - fixed `depth`.
+- AIR diagnostics and provenance.
+- A deterministic non-executing simple-shaft lowering candidate that keeps the semantic feature attached and reports that executable profile-stack/BRep materialization is deferred.
+
+## Intentionally not supported yet
+
+HOLE-X1 does not implement counterbore, countersink, thread/tap geometry, standard/fit libraries, drill-tip geometry, hole groups, patterns, arbitrary datum placement, `upToFace`, `upToNext`, non-planar entry faces, multi-body propagation, or a general 3D boolean authoring surface.
+
+## Reuse and non-reuse
+
+The scaffold reuses prior vocabulary from the recovery/materializer work at the concept level: shaft radius/diameter, through versus blind/depth semantics, profile-stack lowering as an execution lane, provenance, and deterministic diagnostics. It does not move `HoleRecoveryPlan`, `HoleRecoveryPolicy`, FrictionLab `AirProfileStackExtrude`, or `ProfileStackExtrudeSpec` wholesale into the source/AIR authoring model.
+
+This avoids baking recovery-only constraints into the production semantic contract, especially rectangular-box-only hosts, Z-axis-only holes, CIR recovery as the source of truth, or profile-stack layers as the primary authored representation.
+
+## Relationship to `07-holes-are-semantic-features.md`
+
+The semantic rule is that a hole remains a feature until a lower execution layer deliberately derives geometry. HOLE-X1 codifies that split by making `AirHoleFeature` the AIR boundary object and making the current lowering output a candidate plan that explicitly preserves the source feature instead of replacing it with an anonymous cylinder cut.
+
+## Why intent must survive before lowering
+
+Manufacturing features carry identity, placement, end-condition, and provenance that a bare cylinder or BRep subtraction cannot reliably express. Preserving that intent lets later milestones add stack components, standards, PMI, diagnostics, and controlled lowerers without changing the authoring contract or forcing recovery machinery to guess what the user meant.