Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add SURFACE-FEATURE-A2 non-emitting planning bridge

Yuechen Li0e221045147d
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFeaturePlanningBridgeTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFeaturePlanningBridgeTests.cs
new file mode 100644
index 00000000..f59a0d93
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFeaturePlanningBridgeTests.cs
@@ -0,0 +1,90 @@
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfaceFeaturePlanningBridgeTests
+{
+ [Fact]
+ public void SurfaceFeaturePlan_PlanarRoundGroove_ProducesPlanningArtifacts()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g1", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 1.2d, 8d, 0.5d, true);
+ var result = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Planned, result.Status);
+ Assert.Equal(SurfacePatchFamily.Planar, result.HostRequirements!.HostSurfaceFamily);
+ Assert.Equal(SurfaceFeaturePathKind.CircleOnPlane, result.PathRequirements!.PathKind);
+ Assert.Equal(SurfaceFeatureProfileKind.CircularArc, result.ProfileRequirements!.ProfileKind);
+ Assert.Contains(result.RequiredTrimCurveFamilies, t => t.CurveFamily == TrimCurveFamily.Circle);
+ Assert.False(result.MaterializationClaimed);
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_CylindricalRoundGroove_ProducesPlanningArtifacts()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g2", "shaft.side_face", SurfacePatchFamily.Cylindrical, SurfaceFeaturePathKind.CircumferentialOnCylinder, SurfaceFeatureDirection.Remove, 0.6d, 4d, 0.4d, true);
+ var result = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Planned, result.Status);
+ Assert.Equal(SurfacePatchFamily.Cylindrical, result.HostRequirements!.HostSurfaceFamily);
+ Assert.Equal(SurfaceFeaturePathKind.CircumferentialOnCylinder, result.PathRequirements!.PathKind);
+ Assert.Contains(result.PathRequirements.Diagnostics, d => d.Contains("coaxial", StringComparison.OrdinalIgnoreCase));
+ Assert.False(result.MaterializationClaimed);
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_RidgeBead_AdditivePlanning()
+ {
+ 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 = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Planned, result.Status);
+ Assert.Equal(SurfaceFeatureKind.Ridge, result.FeatureKind);
+ Assert.Contains(result.ExpectedPatchFamilies, p => p.Role.Contains("additive", StringComparison.OrdinalIgnoreCase));
+ Assert.False(result.MaterializationClaimed);
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_Thread_RoutesToForgeOrDeferred()
+ {
+ 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 = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Forge, result.Status);
+ Assert.False(result.MaterializationClaimed);
+ Assert.Contains(result.Diagnostics, d => d.Contains("helix", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_GenericTorusBoolean_Rejected()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g3", "body.surface", SurfacePatchFamily.Toroidal, SurfaceFeaturePathKind.CurveOnSurface, SurfaceFeatureDirection.Remove, 0.2d, 2d, 0.1d, true);
+ var result = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Unsupported, result.Status);
+ Assert.Contains(result.Diagnostics, d => d.Contains("Generic torus Boolean", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_InvalidDescriptor_ReturnsInvalidPlan()
+ {
+ var descriptor = new RoundGrooveFeatureDescriptor("g4", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0d, 3d, -1d, true);
+ var result = SurfaceFeaturePlanner.Plan(descriptor);
+
+ Assert.Equal(SurfaceFeaturePlanningStatus.Invalid, result.Status);
+ Assert.False(result.MaterializationClaimed);
+ }
+
+ [Fact]
+ public void SurfaceFeaturePlan_DoesNotClaimMaterialization()
+ {
+ var descriptors = new SurfaceFeatureDescriptor[]
+ {
+ new RoundGrooveFeatureDescriptor("g1", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 1.2d, 8d, 0.5d, true),
+ new RoundGrooveFeatureDescriptor("g2", "shaft.side_face", SurfacePatchFamily.Cylindrical, SurfaceFeaturePathKind.CircumferentialOnCylinder, SurfaceFeatureDirection.Remove, 0.6d, 4d, 0.4d, true),
+ 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 results = descriptors.Select(SurfaceFeaturePlanner.Plan).ToArray();
+ Assert.All(results, plan => Assert.False(plan.MaterializationClaimed));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFeaturePlanningBridge.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFeaturePlanningBridge.cs
new file mode 100644
index 00000000..7f5fd376
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFeaturePlanningBridge.cs
@@ -0,0 +1,154 @@
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum SurfaceFeaturePlanningStatus
+{
+ Planned,
+ Deferred,
+ Forge,
+ Unsupported,
+ Invalid
+}
+
+internal sealed record SurfaceFeatureHostRequirement(
+ SurfacePatchFamily HostSurfaceFamily,
+ string RequiredSelectorKind,
+ string AlignmentConstraint,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceFeaturePathRequirement(
+ SurfaceFeaturePathKind PathKind,
+ IReadOnlyList<string> Constraints,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceFeatureProfileRequirement(
+ SurfaceFeatureProfileKind ProfileKind,
+ string ParametersSummary,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceFeaturePatchExpectation(
+ SurfacePatchFamily SurfaceFamily,
+ string Role,
+ SurfaceFeatureCapabilityTier Capability,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceFeatureTrimRequirement(
+ TrimCurveFamily CurveFamily,
+ TrimCurveCapability Capability,
+ string ExactnessPolicy,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceFeaturePlanningResult(
+ SurfaceFeaturePlanningStatus Status,
+ string FeatureId,
+ SurfaceFeatureKind FeatureKind,
+ SurfaceFeatureCapabilityTier CapabilityTier,
+ bool MaterializationClaimed,
+ SurfaceFeatureHostRequirement? HostRequirements,
+ SurfaceFeaturePathRequirement? PathRequirements,
+ SurfaceFeatureProfileRequirement? ProfileRequirements,
+ IReadOnlyList<SurfaceFeaturePatchExpectation> ExpectedPatchFamilies,
+ IReadOnlyList<SurfaceFeatureTrimRequirement> RequiredTrimCurveFamilies,
+ IReadOnlyList<SurfacePatchFamily> RequiredSurfaceFamilies,
+ IReadOnlyList<string> BlockingReasons,
+ IReadOnlyList<string> Diagnostics);
+
+internal static class SurfaceFeaturePlanner
+{
+ internal static SurfaceFeaturePlanningResult Plan(SurfaceFeatureDescriptor descriptor)
+ {
+ var validation = SurfaceFeatureValidator.Validate(descriptor);
+ var diagnostics = new List<string> { "planning-only: result is non-emitting and does not materialize BRep topology." };
+ diagnostics.AddRange(validation.Diagnostics.Select(d => $"{d.Code}: {d.Message}"));
+
+ if (validation.Status == SurfaceFeatureValidationStatus.Invalid)
+ {
+ return BuildTerminal(SurfaceFeaturePlanningStatus.Invalid, validation, descriptor, ["validation-failed"], diagnostics);
+ }
+
+ if (validation.Status == SurfaceFeatureValidationStatus.Unsupported)
+ {
+ return BuildTerminal(SurfaceFeaturePlanningStatus.Unsupported, validation, descriptor, ["unsupported-intent"], diagnostics);
+ }
+
+ if (validation.CapabilityTier == SurfaceFeatureCapabilityTier.Forge)
+ {
+ diagnostics.Add("forge-route: thread/helical feature planning is routed to Forge in first-wave Core scope.");
+ return BuildTerminal(SurfaceFeaturePlanningStatus.Forge, validation, descriptor, ["thread-helical-complexity"], diagnostics);
+ }
+
+ if (validation.CapabilityTier == SurfaceFeatureCapabilityTier.Deferred)
+ {
+ diagnostics.Add("deferred-route: host/path/profile combination requires deferred pipeline or spline approximation policy.");
+ return BuildTerminal(SurfaceFeaturePlanningStatus.Deferred, validation, descriptor, ["deferred-capability"], diagnostics);
+ }
+
+ var normalizedKind = validation.NormalizedKind;
+ var host = new SurfaceFeatureHostRequirement(
+ descriptor.HostSurfaceFamily,
+ "semantic-host-reference",
+ descriptor.HasAlignmentConstraint ? "required-and-present" : "missing",
+ [$"host={descriptor.HostSurfaceFamily}"]);
+
+ var pathDiagnostics = descriptor.PathKind switch
+ {
+ SurfaceFeaturePathKind.CircleOnPlane => new[] { "path-circle-on-plane: concentric/normal alignment expected." },
+ SurfaceFeaturePathKind.CircumferentialOnCylinder => new[] { "path-circumferential-on-cylinder: coaxial circumferential alignment expected." },
+ _ => new[] { "path-unsupported-for-core-plan" }
+ };
+ var path = new SurfaceFeaturePathRequirement(descriptor.PathKind, ["closed-path", "bounded-first-wave"], pathDiagnostics);
+ var profile = new SurfaceFeatureProfileRequirement(descriptor.ProfileKind, $"radius={descriptor.ProfileRadius:0.###}, depthOrHeight={descriptor.DepthOrHeight:0.###}", ["profile-circular-arc-required-in-first-wave"]);
+
+ var isAdditive = normalizedKind == SurfaceFeatureKind.Ridge || descriptor.Direction == SurfaceFeatureDirection.Add;
+ var patches = new List<SurfaceFeaturePatchExpectation>
+ {
+ new(descriptor.HostSurfaceFamily, "host-replacement-or-retained", SurfaceFeatureCapabilityTier.CoreExact, ["host patch participation expected"]),
+ new(descriptor.HostSurfaceFamily, isAdditive ? "additive-feature-wall" : "removal-feature-wall", SurfaceFeatureCapabilityTier.CoreExact, ["local bounded patch set expected"]),
+ new(SurfacePatchFamily.Toroidal, "round-profile-transition", SurfaceFeatureCapabilityTier.CoreSplineApprox, ["conceptual toroidal/rolled transition may require spline approximation policy in future materializer"])
+ };
+
+ var trims = new List<SurfaceFeatureTrimRequirement>
+ {
+ new(TrimCurveFamily.Circle, TrimCurveCapability.ExactSupported, "exact-when-circular-constraints-hold", ["circular trim loops expected"]),
+ new(TrimCurveFamily.BSpline, TrimCurveCapability.Deferred, "approximation-only-if-policy-allows", ["spline approximation would be explicit and non-exact"])
+ };
+
+ diagnostics.Add("core-plan-ready: descriptor is planned under constrained first-wave surface feature policy.");
+ diagnostics.Add("materialization-not-implemented: planner does not claim patch emission, topology assembly, or STEP exactness.");
+
+ return new(
+ SurfaceFeaturePlanningStatus.Planned,
+ descriptor.FeatureId,
+ normalizedKind,
+ SurfaceFeatureCapabilityTier.CoreExact,
+ MaterializationClaimed: false,
+ HostRequirements: host,
+ PathRequirements: path,
+ ProfileRequirements: profile,
+ ExpectedPatchFamilies: patches,
+ RequiredTrimCurveFamilies: trims,
+ RequiredSurfaceFamilies: [descriptor.HostSurfaceFamily, SurfacePatchFamily.Toroidal],
+ BlockingReasons: ["materialization-not-implemented"],
+ Diagnostics: diagnostics);
+ }
+
+ private static SurfaceFeaturePlanningResult BuildTerminal(
+ SurfaceFeaturePlanningStatus status,
+ SurfaceFeatureValidationResult validation,
+ SurfaceFeatureDescriptor descriptor,
+ IReadOnlyList<string> blockers,
+ IReadOnlyList<string> diagnostics)
+ => new(
+ status,
+ descriptor.FeatureId,
+ validation.NormalizedKind,
+ validation.CapabilityTier,
+ MaterializationClaimed: false,
+ HostRequirements: null,
+ PathRequirements: null,
+ ProfileRequirements: null,
+ ExpectedPatchFamilies: [],
+ RequiredTrimCurveFamilies: [],
+ RequiredSurfaceFamilies: [],
+ BlockingReasons: blockers,
+ Diagnostics: diagnostics);
+}
diff --git a/docs/surface-feature-a2-planning-bridge.md b/docs/surface-feature-a2-planning-bridge.md
new file mode 100644
index 00000000..3a3467ce
--- /dev/null
+++ b/docs/surface-feature-a2-planning-bridge.md
@@ -0,0 +1,92 @@
+# SURFACE-FEATURE-A2: non-emitting feature planning bridge
+
+Date: 2026-05-11
+Status: planning scaffold only (no materialization behavior change)
+
+## Purpose
+
+A2 introduces a planning bridge from validated `SurfaceFeatureDescriptor` intent into structured planning artifacts.
+
+The bridge answers:
+- required host family + semantic host selector expectations,
+- required path/profile constraints,
+- expected patch families,
+- required trim curve families/capabilities,
+- capability route (`CoreExact`, `CoreSplineApprox`, `Forge`, `Deferred`, `Unsupported`) and blockers.
+
+A2 does not emit BRep topology, does not mutate CIR booleans, and does not alter STEP export behavior.
+
+## Planning artifact model
+
+`SurfaceFeaturePlanningResult` captures:
+- planning status (`Planned`, `Deferred`, `Forge`, `Unsupported`, `Invalid`),
+- feature identity/kind and capability tier,
+- `MaterializationClaimed=false` always,
+- host/path/profile requirement records,
+- expected patch and trim requirements,
+- required surface families,
+- blocking reasons and diagnostics.
+
+Supporting records:
+- `SurfaceFeatureHostRequirement`
+- `SurfaceFeaturePathRequirement`
+- `SurfaceFeatureProfileRequirement`
+- `SurfaceFeaturePatchExpectation`
+- `SurfaceFeatureTrimRequirement`
+
+## First-wave planning behavior
+
+### Planar round groove
+- Host requirement: `Planar`.
+- Path requirement: `CircleOnPlane` with constrained circular alignment diagnostics.
+- Profile requirement: `CircularArc` with bounded radius/depth summary.
+- Expected patches: host retained/replacement + groove wall/transition expectations.
+- Trim requirements: exact circle trims and deferred BSpline approximation policy notes.
+- Status: `Planned`, still non-emitting.
+
+### Cylindrical circumferential round groove
+- Host requirement: `Cylindrical`.
+- Path requirement: `CircumferentialOnCylinder` with coaxial/circumferential alignment diagnostics.
+- Profile requirement: `CircularArc`.
+- Expected patches/trims: same scaffold shape as planar with cylindrical host role.
+- Status: `Planned`, still non-emitting.
+
+### Ridge/bead additive
+- Normalized kind is ridge family.
+- Additive direction is represented as additive patch role expectations.
+- Status: `Planned`, non-emitting.
+
+### Thread
+- Classified to `Forge` planning status.
+- Diagnostics explicitly call out helical path/topology/export complexity.
+- No Core materialization claim.
+
+### Generic torus Boolean / unsupported
+- Rejected as `Unsupported` with explicit diagnostic that generic torus Boolean remains unsupported.
+
+### Invalid descriptors
+- Return `Invalid` planning status with validation diagnostics.
+
+## Forge/deferred routing
+
+Planning delegates admissibility normalization to A1 validation contract:
+- helical/thread -> `Forge`,
+- arbitrary curve-on-surface path/profile mismatch -> `Deferred`,
+- unsupported host/path or toroidal generic intent -> `Unsupported`.
+
+## SEM-A0 guardrails
+
+A2 preserves SEM-A0 boundaries:
+- no generated topology naming,
+- no selector namespace expansion,
+- no provenance schema broadening,
+- no topology/BRep emission.
+
+## JudgmentEngine decision
+
+A2 planner is deterministic descriptor-to-plan mapping with no competing bounded candidates at runtime.
+Therefore `JudgmentEngine` is intentionally not used here; diagnostic notes are still explicit via validation + planning blockers.
+
+## Recommended SURFACE-FEATURE-A3
+
+Implement feature-specific dry-run patch generation that consumes `SurfaceFeaturePlanningResult` for planar/cylindrical constrained grooves/ridges and feeds readiness diagnostics into existing materialization-readiness reporting, while keeping `MaterializationClaimed=false` until real BRep emission is implemented.