Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.