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