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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.