Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add SURFACE-FEATURE-A3 planar groove dry-run generator
Yuechen Lica1adfd2a011
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDryRunGeneratorTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDryRunGeneratorTests.csnew file mode 100644index 00000000..38268c08--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureDryRunGeneratorTests.cs@@ -0,0 +1,71 @@+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class SurfaceFeatureDryRunGeneratorTests+{+ [Fact]+ public void SurfaceFeatureDryRun_PlanarRoundGroove_ProducesPatchExpectations()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g1", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 1.2d, 8d, 0.5d, true);++ var result = SurfaceFeatureDryRunGenerator.Generate(descriptor);++ Assert.True(result.Success);+ Assert.Equal(SurfaceFeatureDryRunStatus.Planned, result.Status);+ Assert.False(result.MaterializationClaimed);+ Assert.Contains(result.PatchExpectations, p => p.PatchRole == SurfaceFeaturePatchRole.HostRetainedPlanarPatch && p.SurfaceFamily == SurfacePatchFamily.Planar);+ Assert.Contains(result.PatchExpectations, p => p.PatchRole == SurfaceFeaturePatchRole.GrooveWallPatch);+ }++ [Fact]+ public void SurfaceFeatureDryRun_PlanarRoundGroove_ProducesTrimExpectations()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g2", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0.8d, 6d, 0.3d, true);++ var result = SurfaceFeatureDryRunGenerator.Generate(descriptor);++ Assert.True(result.Success);+ Assert.Contains(result.TrimExpectations, t => t.CurveFamily == TrimCurveFamily.Circle && t.TrimRole == SurfaceFeatureTrimRole.OuterGrooveBoundary);+ Assert.Contains(result.TrimExpectations, t => t.CurveFamily == TrimCurveFamily.Circle && t.TrimRole == SurfaceFeatureTrimRole.InnerGrooveBoundary);+ Assert.Contains(result.TrimExpectations, t => t.CurveFamily == TrimCurveFamily.BSpline && t.Capability == TrimCurveCapability.Deferred);+ }++ [Fact]+ public void SurfaceFeatureDryRun_PlanarRoundGroove_DiagnosticsAreExplicit()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g3", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0.5d, 4d, 0.2d, true);++ var result = SurfaceFeatureDryRunGenerator.Generate(descriptor);++ Assert.Contains(result.Diagnostics, d => d.Contains("dry-run-only", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Diagnostics, d => d.Contains("no-brep-emission", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Diagnostics, d => d.Contains("generic-torus-boolean-not-used", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void SurfaceFeatureDryRun_InvalidDescriptor_FailsFromPlanner()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g4", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0d, 3d, -0.1d, true);++ var result = SurfaceFeatureDryRunGenerator.Generate(descriptor);++ Assert.False(result.Success);+ Assert.Equal(SurfaceFeatureDryRunStatus.Invalid, result.Status);+ Assert.Empty(result.PatchExpectations);+ Assert.Empty(result.TrimExpectations);+ }++ [Fact]+ public void SurfaceFeatureDryRun_Thread_RemainsForgeDeferred()+ {+ 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 = SurfaceFeatureDryRunGenerator.Generate(descriptor);++ Assert.False(result.Success);+ Assert.Equal(SurfaceFeatureDryRunStatus.Forge, result.Status);+ Assert.False(result.MaterializationClaimed);+ Assert.Empty(result.PatchExpectations);+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDryRunGenerator.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDryRunGenerator.csnew file mode 100644index 00000000..996658ba--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureDryRunGenerator.cs@@ -0,0 +1,176 @@+namespace Aetheris.Kernel.Firmament.Execution;++internal enum SurfaceFeatureDryRunStatus+{+ Planned,+ Deferred,+ Forge,+ Unsupported,+ Invalid+}++internal enum SurfaceFeaturePatchRole+{+ HostRetainedPlanarPatch,+ GrooveWallPatch,+ GrooveBottomOrProfilePatch,+ DeferredPatch+}++internal enum SurfaceFeatureTrimRole+{+ OuterGrooveBoundary,+ InnerGrooveBoundary,+ ProfileBoundary,+ DeferredTrim+}++internal sealed record SurfaceFeaturePatchDryRun(+ SurfaceFeaturePatchRole PatchRole,+ SurfacePatchFamily SurfaceFamily,+ string ExpectedGeometry,+ SurfaceFeatureCapabilityTier Capability,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeatureTrimDryRun(+ SurfaceFeatureTrimRole TrimRole,+ TrimCurveFamily CurveFamily,+ TrimCurveCapability Capability,+ string ExactnessPolicy,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeatureDryRunResult(+ bool Success,+ string FeatureId,+ SurfaceFeatureKind FeatureKind,+ SurfaceFeatureDryRunStatus Status,+ SurfaceFeatureCapabilityTier CapabilityTier,+ bool MaterializationClaimed,+ IReadOnlyList<SurfaceFeaturePatchDryRun> PatchExpectations,+ IReadOnlyList<SurfaceFeatureTrimDryRun> TrimExpectations,+ IReadOnlyList<string> BlockingReasons,+ IReadOnlyList<string> Diagnostics);++internal static class SurfaceFeatureDryRunGenerator+{+ internal static SurfaceFeatureDryRunResult Generate(SurfaceFeatureDescriptor descriptor)+ {+ var plan = SurfaceFeaturePlanner.Plan(descriptor);+ var diagnostics = new List<string>+ {+ "dry-run-only: reports patch/trim expectations and does not emit topology or mutate BRep.",+ "generic-torus-boolean-not-used: dry-run stays in surface feature planning domain."+ };+ diagnostics.AddRange(plan.Diagnostics);++ if (plan.Status != SurfaceFeaturePlanningStatus.Planned)+ {+ diagnostics.Add("planner-terminal: dry-run stopped because planning did not reach Planned status.");+ return new(+ Success: false,+ FeatureId: plan.FeatureId,+ FeatureKind: plan.FeatureKind,+ Status: MapStatus(plan.Status),+ CapabilityTier: plan.CapabilityTier,+ MaterializationClaimed: false,+ PatchExpectations: [],+ TrimExpectations: [],+ BlockingReasons: plan.BlockingReasons,+ Diagnostics: diagnostics);+ }++ if (!IsPlanarRoundGroove(descriptor, plan))+ {+ diagnostics.Add("dry-run-deferred: current A3 generator only handles planar round groove remove-path profile constraints.");+ return new(+ Success: false,+ FeatureId: plan.FeatureId,+ FeatureKind: plan.FeatureKind,+ Status: SurfaceFeatureDryRunStatus.Deferred,+ CapabilityTier: SurfaceFeatureCapabilityTier.Deferred,+ MaterializationClaimed: false,+ PatchExpectations: [],+ TrimExpectations: [],+ BlockingReasons: ["dry-run-scope-limited"],+ Diagnostics: diagnostics);+ }++ var patches = new List<SurfaceFeaturePatchDryRun>+ {+ new(+ SurfaceFeaturePatchRole.HostRetainedPlanarPatch,+ SurfacePatchFamily.Planar,+ "retained-host-planar-regions-around-groove-annulus",+ SurfaceFeatureCapabilityTier.CoreExact,+ ["host planar retention expected; exact patch decomposition remains non-emitting/planned only"]),+ new(+ SurfaceFeaturePatchRole.GrooveWallPatch,+ SurfacePatchFamily.Toroidal,+ "revolved-round-groove-wall-like-surface",+ SurfaceFeatureCapabilityTier.CoreSplineApprox,+ ["future materializer may represent groove wall with toroidal or spline-approx policy; exact emission not claimed"]),+ new(+ SurfaceFeaturePatchRole.GrooveBottomOrProfilePatch,+ SurfacePatchFamily.Toroidal,+ "circular-arc-profile-bottom-transition",+ SurfaceFeatureCapabilityTier.CoreSplineApprox,+ ["profile/bottom transition expected from circular arc profile; deferred until BRep surface emission milestone"])+ };++ var trims = new List<SurfaceFeatureTrimDryRun>+ {+ new(+ SurfaceFeatureTrimRole.OuterGrooveBoundary,+ TrimCurveFamily.Circle,+ TrimCurveCapability.ExactSupported,+ "exact-when-circle-on-plane-constraints-hold",+ ["outer circular boundary trim expected on planar host"]),+ new(+ SurfaceFeatureTrimRole.InnerGrooveBoundary,+ TrimCurveFamily.Circle,+ TrimCurveCapability.ExactSupported,+ "exact-when-circle-on-plane-constraints-hold",+ ["inner circular boundary trim expected on planar host"]),+ new(+ SurfaceFeatureTrimRole.ProfileBoundary,+ TrimCurveFamily.BSpline,+ TrimCurveCapability.Deferred,+ "approximation-policy-required-for-non-elementary-profile-coupling",+ ["profile/groove-wall trim coupling may require explicit BSpline approximation policy in future"])+ };++ diagnostics.Add("constraint-accepted: planar host + circle-on-plane path + circular-arc profile + remove direction recognized.");+ diagnostics.Add("no-brep-emission: dry-run does not emit faces, edges, loops, or coedges.");+ diagnostics.Add("materialization-not-implemented: this milestone stops at structured expectations and blockers.");++ return new(+ Success: true,+ FeatureId: plan.FeatureId,+ FeatureKind: plan.FeatureKind,+ Status: SurfaceFeatureDryRunStatus.Planned,+ CapabilityTier: SurfaceFeatureCapabilityTier.CoreExact,+ MaterializationClaimed: false,+ PatchExpectations: patches,+ TrimExpectations: trims,+ BlockingReasons: ["brep-materialization-not-implemented", "topology-emission-not-implemented", "step-exactness-not-claimed"],+ Diagnostics: diagnostics);+ }++ private static bool IsPlanarRoundGroove(SurfaceFeatureDescriptor descriptor, SurfaceFeaturePlanningResult plan)+ => plan.FeatureKind == SurfaceFeatureKind.RoundGroove+ && descriptor.HostSurfaceFamily == SurfacePatchFamily.Planar+ && descriptor.PathKind == SurfaceFeaturePathKind.CircleOnPlane+ && descriptor.ProfileKind == SurfaceFeatureProfileKind.CircularArc+ && descriptor.Direction == SurfaceFeatureDirection.Remove;++ private static SurfaceFeatureDryRunStatus MapStatus(SurfaceFeaturePlanningStatus status)+ => status switch+ {+ SurfaceFeaturePlanningStatus.Planned => SurfaceFeatureDryRunStatus.Planned,+ SurfaceFeaturePlanningStatus.Deferred => SurfaceFeatureDryRunStatus.Deferred,+ SurfaceFeaturePlanningStatus.Forge => SurfaceFeatureDryRunStatus.Forge,+ SurfaceFeaturePlanningStatus.Unsupported => SurfaceFeatureDryRunStatus.Unsupported,+ SurfaceFeaturePlanningStatus.Invalid => SurfaceFeatureDryRunStatus.Invalid,+ _ => SurfaceFeatureDryRunStatus.Unsupported+ };+}diff --git a/docs/surface-feature-a3-planar-groove-dry-run.md b/docs/surface-feature-a3-planar-groove-dry-run.mdnew file mode 100644index 00000000..9e5c4432--- /dev/null+++ b/docs/surface-feature-a3-planar-groove-dry-run.md@@ -0,0 +1,92 @@+# SURFACE-FEATURE-A3 — planar round-groove dry-run patch generation++## Purpose++SURFACE-FEATURE-A3 consumes SURFACE-FEATURE-A2 planning output and produces a **non-emitting dry-run report** for one constrained feature intent:++- `RoundGrooveFeatureDescriptor`+- host: `SurfacePatchFamily.Planar`+- path: `SurfaceFeaturePathKind.CircleOnPlane`+- profile: `SurfaceFeatureProfileKind.CircularArc`+- direction: `SurfaceFeatureDirection.Remove`++This milestone does not emit BRep topology or materialize geometry.++## Supported descriptor shape++A3 supports exactly the constrained planar round-groove descriptor above.+All other descriptors are returned as planner-terminal (`Invalid` / `Unsupported` / `Forge` / `Deferred`) or A3 dry-run deferred scope.++## Dry-run output model++`SurfaceFeatureDryRunResult` reports:++- planned/deferred/terminal status,+- capability tier,+- `MaterializationClaimed = false`,+- structured patch expectations,+- structured trim expectations,+- explicit blockers and diagnostics.++Patch expectations are represented by `SurfaceFeaturePatchDryRun` and include roles such as:++- `HostRetainedPlanarPatch`+- `GrooveWallPatch`+- `GrooveBottomOrProfilePatch`+- `DeferredPatch`++Trim expectations are represented by `SurfaceFeatureTrimDryRun` and include roles such as:++- `OuterGrooveBoundary`+- `InnerGrooveBoundary`+- `ProfileBoundary`+- `DeferredTrim`++## Patch/trim expectation policy++For constrained planar circular grooves, A3 reports:++- retained planar host patch expectations around the annular groove region,+- groove wall/profile transition expectations as toroidal/revolved-profile-like surfaces,+- circular boundary trim expectations on planar host,+- deferred `BSpline` policy for profile coupling when exact elementary curve representation is not yet available.++## Exact vs spline/deferred++A3 can claim **planning readiness only**.+It does not claim exact emitted toroidal/profile patches or STEP exactness.+Any spline route is diagnostic-only and must remain explicit in the dry-run report.++## Explicit non-goals++A3 does **not** implement:++- BRep face/edge/loop/coedge emission,+- topology materialization,+- STEP export behavior changes,+- CIR Boolean mutation,+- generic torus Boolean support,+- thread geometry,+- public CLI exposure,+- generated topology naming.++## SEM-A0 guardrails++A3 preserves SEM-A0 boundaries:++- no generated topology naming,+- no expansion of public topology identity policy,+- provenance remains descriptor/planning-oriented.++## JudgmentEngine usage decision++A3 dry-run generation is deterministic descriptor-to-report mapping for one accepted intent.+No competing strategy set is currently selected at runtime; therefore `JudgmentEngine` is intentionally not used in this milestone.++## Next milestone (A4)++SURFACE-FEATURE-A4 should prototype **internal patch/trim evidence realization** for the planar groove case:++- bind dry-run patch roles to concrete internal evidence structures,+- keep non-emitting behavior,+- harden exact-vs-approx policy boundaries before any BRep materialization milestone.