Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add surface-feature A1 descriptor taxonomy and validator scaffold

Yuechen Li9056eefd6cbd
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDescriptorValidationTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDescriptorValidationTests.cs
new file mode 100644
index 00000000..1a006475
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDescriptorValidationTests.cs
@@ -0,0 +1,72 @@
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfaceFeatureDescriptorValidationTests
+{
+ [Fact]
+ public void SurfaceFeature_RoundGroove_PlanarCircle_Validates()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g1", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 1.2d, 8d, 0.5d, true);
+
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+
+ Assert.True(result.IsSuccess);
+ Assert.Equal(SurfaceFeatureValidationStatus.Valid, result.Status);
+ Assert.Equal(SurfaceFeatureCapabilityTier.CoreExact, result.CapabilityTier);
+ Assert.False(result.MaterializationClaimed);
+ }
+
+ [Fact]
+ public void SurfaceFeature_RoundGroove_CylindricalCircumferential_Validates()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g2", "shaft.side_face", SurfacePatchFamily.Cylindrical, SurfaceFeaturePathKind.CircumferentialOnCylinder, SurfaceFeatureDirection.Remove, 0.6d, 4d, 0.4d, true);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.True(result.IsSuccess);
+ }
+
+ [Fact]
+ public void SurfaceFeature_RidgeOrBead_ValidatesAsAdditiveSurfaceFeature()
+ {
+ var descriptor = new SurfaceFeatureDescriptor("r1", SurfaceFeatureKind.Bead, "shaft.side_face", SurfacePatchFamily.Cylindrical, SurfaceFeaturePathKind.CircumferentialOnCylinder, SurfaceFeatureProfileKind.CircularArc, SurfaceFeatureDirection.Add, 0.4d, 5d, 0.3d, true, SurfaceFeatureCapabilityTier.CoreExact);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.True(result.IsSuccess);
+ Assert.Equal(SurfaceFeatureKind.Ridge, result.NormalizedKind);
+ }
+
+ [Fact]
+ public void SurfaceFeature_Thread_ClassifiedForgeOrDeferred()
+ {
+ var descriptor = new SurfaceFeatureDescriptor("t1", SurfaceFeatureKind.Thread, "shaft.side_face", SurfacePatchFamily.Cylindrical, SurfaceFeaturePathKind.HelixOnCylinder, SurfaceFeatureProfileKind.VProfile, SurfaceFeatureDirection.Remove, 0.2d, 4d, 0.1d, true, SurfaceFeatureCapabilityTier.Deferred);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.Equal(SurfaceFeatureValidationStatus.WarningDeferred, result.Status);
+ Assert.Equal(SurfaceFeatureCapabilityTier.Forge, result.CapabilityTier);
+ Assert.Contains(result.Diagnostics, d => d.Message.Contains("helix", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFeature_GenericTorusBoolean_IsRejectedOrDeferred()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g3", "body.surface", SurfacePatchFamily.Toroidal, SurfaceFeaturePathKind.CurveOnSurface, SurfaceFeatureDirection.Remove, 0.2d, 2d, 0.1d, true);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.Equal(SurfaceFeatureValidationStatus.Unsupported, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Message.Contains("Generic torus Boolean remains unsupported", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFeature_InvalidParameters_Rejected()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g4", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0d, 3d, -1d, true);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.Equal(SurfaceFeatureValidationStatus.Invalid, result.Status);
+ }
+
+ [Fact]
+ public void SurfaceFeature_ArbitraryCurvePath_RejectedOrDeferred()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g5", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CurveOnSurface, SurfaceFeatureDirection.Remove, 0.5d, 3d, 0.2d, true);
+ var result = SurfaceFeatureValidator.Validate(descriptor);
+ Assert.Equal(SurfaceFeatureValidationStatus.WarningDeferred, result.Status);
+ Assert.Equal(SurfaceFeatureCapabilityTier.Deferred, result.CapabilityTier);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDescriptors.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDescriptors.cs
new file mode 100644
index 00000000..bb4cd021
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDescriptors.cs
@@ -0,0 +1,204 @@
+using System.Globalization;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum SurfaceFeatureKind
+{
+ RoundGroove,
+ Ridge,
+ Bead,
+ Thread,
+ Emboss,
+ Deboss,
+ Knurl,
+ Dimple,
+ Unsupported
+}
+
+internal enum SurfaceFeaturePathKind
+{
+ CircleOnPlane,
+ CircumferentialOnCylinder,
+ LatitudeOnSphere,
+ HelixOnCylinder,
+ CurveOnSurface,
+ Unsupported
+}
+
+internal enum SurfaceFeatureProfileKind
+{
+ CircularArc,
+ VProfile,
+ Trapezoid,
+ FlatBottom,
+ Custom,
+ Unsupported
+}
+
+internal enum SurfaceFeatureDirection
+{
+ Remove,
+ Add
+}
+
+internal enum SurfaceFeatureCapabilityTier
+{
+ CoreExact,
+ CoreSplineApprox,
+ Forge,
+ Deferred,
+ Unsupported
+}
+
+internal enum SurfaceFeatureValidationStatus
+{
+ Valid,
+ WarningDeferred,
+ Unsupported,
+ Invalid
+}
+
+internal record SurfaceFeatureDescriptor(
+ string FeatureId,
+ SurfaceFeatureKind FeatureKind,
+ string HostSurfaceRef,
+ SurfacePatchFamily HostSurfaceFamily,
+ SurfaceFeaturePathKind PathKind,
+ SurfaceFeatureProfileKind ProfileKind,
+ SurfaceFeatureDirection Direction,
+ double ProfileRadius,
+ double CenterlineRadius,
+ double DepthOrHeight,
+ bool HasAlignmentConstraint,
+ SurfaceFeatureCapabilityTier CapabilityTarget,
+ IReadOnlyDictionary<string, double>? PathParameters = null,
+ IReadOnlyDictionary<string, double>? ProfileParameters = null,
+ IReadOnlyDictionary<string, double>? ExtentParameters = null);
+
+internal sealed record RoundGrooveFeatureDescriptor(
+ string FeatureId,
+ string HostSurfaceRef,
+ SurfacePatchFamily HostSurfaceFamily,
+ SurfaceFeaturePathKind PathKind,
+ SurfaceFeatureDirection Direction,
+ double ProfileRadius,
+ double CenterlineRadius,
+ double DepthOrHeight,
+ bool HasAlignmentConstraint,
+ SurfaceFeatureCapabilityTier CapabilityTarget = SurfaceFeatureCapabilityTier.CoreExact)
+ : SurfaceFeatureDescriptor(
+ FeatureId,
+ SurfaceFeatureKind.RoundGroove,
+ HostSurfaceRef,
+ HostSurfaceFamily,
+ PathKind,
+ SurfaceFeatureProfileKind.CircularArc,
+ Direction,
+ ProfileRadius,
+ CenterlineRadius,
+ DepthOrHeight,
+ HasAlignmentConstraint,
+ CapabilityTarget);
+
+internal sealed record SurfaceFeatureValidationDiagnostic(string Code, string Message);
+
+internal sealed record SurfaceFeatureValidationResult(
+ SurfaceFeatureValidationStatus Status,
+ SurfaceFeatureCapabilityTier CapabilityTier,
+ bool MaterializationClaimed,
+ SurfaceFeatureKind NormalizedKind,
+ IReadOnlyList<SurfaceFeatureValidationDiagnostic> Diagnostics)
+{
+ public bool IsSuccess => Status == SurfaceFeatureValidationStatus.Valid;
+}
+
+internal static class SurfaceFeatureValidator
+{
+ public static SurfaceFeatureValidationResult Validate(SurfaceFeatureDescriptor descriptor)
+ {
+ var diagnostics = new List<SurfaceFeatureValidationDiagnostic>();
+ var capability = descriptor.CapabilityTarget;
+
+ if (descriptor.FeatureKind == SurfaceFeatureKind.Thread || descriptor.PathKind == SurfaceFeaturePathKind.HelixOnCylinder)
+ {
+ diagnostics.Add(new("surface-feature-thread-deferred", "Thread and helical surface features are Forge/deferred due to helix topology and export complexity in first-wave Core scope."));
+ return new(SurfaceFeatureValidationStatus.WarningDeferred, SurfaceFeatureCapabilityTier.Forge, false, SurfaceFeatureKind.Thread, diagnostics);
+ }
+
+ if (descriptor.FeatureKind == SurfaceFeatureKind.RoundGroove && descriptor.Direction == SurfaceFeatureDirection.Add)
+ {
+ diagnostics.Add(new("surface-feature-roundgroove-add-normalized", "Round groove descriptor with additive direction normalized to ridge/bead family for first-wave constrained surface features."));
+ return Validate(descriptor with { FeatureKind = SurfaceFeatureKind.Ridge }, diagnostics);
+ }
+
+ return Validate(descriptor, diagnostics);
+ }
+
+ private static SurfaceFeatureValidationResult Validate(SurfaceFeatureDescriptor descriptor, List<SurfaceFeatureValidationDiagnostic> diagnostics)
+ {
+ if (descriptor.HostSurfaceFamily == SurfacePatchFamily.Toroidal)
+ {
+ diagnostics.Add(new("surface-feature-generic-torus-unsupported", "Generic torus Boolean remains unsupported for exact materialization and must not be modeled as unconstrained surface feature intent."));
+ return new(SurfaceFeatureValidationStatus.Unsupported, SurfaceFeatureCapabilityTier.Unsupported, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ if (descriptor.ProfileRadius <= 0d || descriptor.CenterlineRadius <= 0d || descriptor.DepthOrHeight <= 0d)
+ {
+ diagnostics.Add(new("surface-feature-invalid-extent", string.Format(CultureInfo.InvariantCulture, "Profile radius ({0}), centerline radius ({1}), and depth/height ({2}) must be positive.", descriptor.ProfileRadius, descriptor.CenterlineRadius, descriptor.DepthOrHeight)));
+ return new(SurfaceFeatureValidationStatus.Invalid, SurfaceFeatureCapabilityTier.Unsupported, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ if (!descriptor.HasAlignmentConstraint)
+ {
+ diagnostics.Add(new("surface-feature-misaligned", "Surface feature is missing required host/path alignment constraint for constrained first-wave validation."));
+ return new(SurfaceFeatureValidationStatus.Invalid, SurfaceFeatureCapabilityTier.Unsupported, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ if (descriptor.PathKind == SurfaceFeaturePathKind.CurveOnSurface)
+ {
+ diagnostics.Add(new("surface-feature-arbitrary-path-deferred", "Arbitrary CurveOnSurface path is out of first-wave constrained scope; defer to Forge/deferred surface feature pipeline."));
+ return new(SurfaceFeatureValidationStatus.WarningDeferred, SurfaceFeatureCapabilityTier.Deferred, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ var hostPathSupported = descriptor switch
+ {
+ { HostSurfaceFamily: SurfacePatchFamily.Planar, PathKind: SurfaceFeaturePathKind.CircleOnPlane } => true,
+ { HostSurfaceFamily: SurfacePatchFamily.Cylindrical, PathKind: SurfaceFeaturePathKind.CircumferentialOnCylinder } => true,
+ _ => false
+ };
+
+ if (!hostPathSupported)
+ {
+ diagnostics.Add(new("surface-feature-host-path-unsupported", $"Unsupported host/path combination for first-wave constrained policy: {descriptor.HostSurfaceFamily} + {descriptor.PathKind}."));
+ return new(SurfaceFeatureValidationStatus.Unsupported, SurfaceFeatureCapabilityTier.Unsupported, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ if (descriptor.ProfileKind != SurfaceFeatureProfileKind.CircularArc)
+ {
+ diagnostics.Add(new("surface-feature-profile-deferred", $"Profile kind {descriptor.ProfileKind} is deferred in first-wave constrained round groove/ridge validation."));
+ return new(SurfaceFeatureValidationStatus.WarningDeferred, SurfaceFeatureCapabilityTier.Deferred, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ var normalized = descriptor.FeatureKind is SurfaceFeatureKind.Bead ? SurfaceFeatureKind.Ridge : descriptor.FeatureKind;
+ if (normalized is not (SurfaceFeatureKind.RoundGroove or SurfaceFeatureKind.Ridge))
+ {
+ diagnostics.Add(new("surface-feature-kind-deferred", $"Feature kind {descriptor.FeatureKind} is not in first-wave Core constrained family and is deferred."));
+ return new(SurfaceFeatureValidationStatus.WarningDeferred, SurfaceFeatureCapabilityTier.Deferred, false, descriptor.FeatureKind, diagnostics);
+ }
+
+ if (normalized == SurfaceFeatureKind.RoundGroove && descriptor.Direction != SurfaceFeatureDirection.Remove)
+ {
+ diagnostics.Add(new("surface-feature-direction-invalid", "Round groove requires Remove direction under first-wave constrained policy."));
+ return new(SurfaceFeatureValidationStatus.Invalid, SurfaceFeatureCapabilityTier.Unsupported, false, normalized, diagnostics);
+ }
+
+ if (normalized == SurfaceFeatureKind.Ridge && descriptor.Direction != SurfaceFeatureDirection.Add)
+ {
+ diagnostics.Add(new("surface-feature-direction-invalid", "Ridge/bead requires Add direction under first-wave constrained policy."));
+ return new(SurfaceFeatureValidationStatus.Invalid, SurfaceFeatureCapabilityTier.Unsupported, false, normalized, diagnostics);
+ }
+
+ diagnostics.Add(new("surface-feature-valid-planned", "Descriptor validates as planned constrained surface feature; no materialization is claimed in SURFACE-FEATURE-A1."));
+ return new(SurfaceFeatureValidationStatus.Valid, SurfaceFeatureCapabilityTier.CoreExact, false, normalized, diagnostics);
+ }
+}
diff --git a/docs/surface-feature-a1-descriptors.md b/docs/surface-feature-a1-descriptors.md
new file mode 100644
index 00000000..dcf834d9
--- /dev/null
+++ b/docs/surface-feature-a1-descriptors.md
@@ -0,0 +1,69 @@
+# SURFACE-FEATURE-A1: descriptors, capability taxonomy, and validation-only contracts
+
+Date: 2026-05-11
+Status: descriptor-first scaffold only (no materialization change)
+
+## Scope
+
+This milestone introduces internal, test-facing surface feature vocabulary and validation contracts so groove/ridge-like intent is represented semantically rather than as arbitrary boolean tool-body subtraction/union.
+
+Explicitly out of scope:
+- BRep face/edge/vertex emission,
+- topology naming expansion (SEM-A0 guardrails remain in force),
+- STEP behavior changes,
+- CIR boolean behavior changes,
+- generic torus boolean materialization,
+- thread geometry generation.
+
+## Taxonomy
+
+Added descriptor taxonomy includes:
+- `SurfaceFeatureKind`: `RoundGroove`, `Ridge`, `Bead`, `Thread`, `Emboss`, `Deboss`, `Knurl`, `Dimple`, `Unsupported`.
+- Host family alignment reuses existing `SurfacePatchFamily`: `Planar`, `Cylindrical`, `Conical`, `Spherical`, `Toroidal`, `Spline`, `Unsupported`.
+- `SurfaceFeaturePathKind`: `CircleOnPlane`, `CircumferentialOnCylinder`, `LatitudeOnSphere`, `HelixOnCylinder`, `CurveOnSurface`, `Unsupported`.
+- `SurfaceFeatureProfileKind`: `CircularArc`, `VProfile`, `Trapezoid`, `FlatBottom`, `Custom`, `Unsupported`.
+- `SurfaceFeatureDirection`: `Remove` and `Add`.
+- `SurfaceFeatureCapabilityTier`: `CoreExact`, `CoreSplineApprox`, `Forge`, `Deferred`, `Unsupported`.
+- `SurfaceFeatureValidationStatus`: `Valid`, `WarningDeferred`, `Unsupported`, `Invalid`.
+
+## Descriptor-first model
+
+Primary internal model:
+- `SurfaceFeatureDescriptor`: feature id/kind, host surface reference + family, path kind, profile kind, direction, bounded dimensions, alignment flag, capability target, and optional parameter dictionaries.
+- `RoundGrooveFeatureDescriptor`: bounded constrained round-groove descriptor for first-wave planar/cylindrical circular/circumferential validation.
+
+A1 keeps this internal and diagnostic-rich; it does not claim runtime surface-feature materialization.
+
+## Validation-only contract
+
+`SurfaceFeatureValidator.Validate(...)` returns `SurfaceFeatureValidationResult` containing:
+- status,
+- capability tier,
+- explicit `MaterializationClaimed=false` indicator,
+- normalized family classification,
+- precise diagnostics.
+
+### First-wave validation policy
+
+Valid/planned (`CoreExact` target, still no materialization claim):
+- round groove on planar host with circular path and circular-arc profile,
+- round groove on cylindrical host with circumferential path and circular-arc profile,
+- ridge/bead additive counterpart under the same constraints.
+
+Deferred/unsupported:
+- `Thread`/helical path: classified Forge/deferred due to helix topology/export complexity,
+- arbitrary `CurveOnSurface` path: deferred,
+- toroidal/generic torus-like modeling: unsupported with explicit diagnostic that generic torus boolean remains unsupported for exact materialization.
+
+Invalid:
+- non-positive radii/depth/height,
+- missing alignment/coaxiality-style constraint,
+- direction/sign mismatch against kind constraints.
+
+## SEM-A0 guardrails maintained
+
+No selector namespace expansion, no generated topology naming, and no provenance model broadening are introduced in A1.
+
+## Recommended SURFACE-FEATURE-A2
+
+Implement planning bridge from validated descriptors into non-emitting feature planning artifacts (host patch targeting + readiness diagnostics), still without BRep emission, then stage bounded materialization in a later milestone.