Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add planar round-groove evidence scaffold from A3 dry-run
Yuechen Lie346f6f734cc
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureEvidenceGeneratorTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureEvidenceGeneratorTests.csnew file mode 100644index 00000000..51eca4e1--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFeatureEvidenceGeneratorTests.cs@@ -0,0 +1,84 @@+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class SurfaceFeatureEvidenceGeneratorTests+{+ [Fact]+ public void SurfaceFeatureEvidence_PlanarRoundGroove_ProducesEvidence()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g1", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 1.2d, 8d, 0.5d, true);++ var result = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.True(result.Success);+ Assert.Equal(SurfaceFeatureEvidenceStatus.Planned, result.Status);+ Assert.False(result.MaterializationClaimed);+ Assert.NotNull(result.Evidence);+ Assert.Equal(SurfaceFeatureGeometryStatus.DescriptorMissing, result.Evidence!.PathEvidence.GeometryStatus);+ Assert.Equal(SurfaceFeatureProfileKind.CircularArc, result.Evidence.ProfileEvidence.ProfileKind);+ }++ [Fact]+ public void SurfaceFeatureEvidence_PlanarRoundGroove_PatchRolesPresent()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g2", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0.8d, 6d, 0.3d, true);++ var result = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.True(result.Success);+ Assert.Contains(result.Evidence!.PatchRoles, p => p.Role == SurfaceFeaturePatchRole.HostRetainedPlanarPatch && p.SurfaceFamily == SurfacePatchFamily.Planar);+ Assert.Contains(result.Evidence.PatchRoles, p => p.Role == SurfaceFeaturePatchRole.GrooveWallPatch);+ }++ [Fact]+ public void SurfaceFeatureEvidence_PlanarRoundGroove_TrimRolesPresent()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g3", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0.5d, 4d, 0.2d, true);++ var result = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.True(result.Success);+ Assert.Contains(result.Evidence!.TrimRoles, t => t.Role == SurfaceFeatureTrimRole.OuterGrooveBoundary && t.CurveFamily == TrimCurveFamily.Circle);+ Assert.Contains(result.Evidence.TrimRoles, t => t.Role == SurfaceFeatureTrimRole.InnerGrooveBoundary && t.CurveFamily == TrimCurveFamily.Circle);+ Assert.Contains(result.Evidence.TrimRoles, t => t.Role == SurfaceFeatureTrimRole.ProfileBoundary && t.Capability == TrimCurveCapability.Deferred);+ }++ [Fact]+ public void SurfaceFeatureEvidence_PlanarRoundGroove_DiagnosticsAreExplicit()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g4", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0.5d, 4d, 0.2d, true);++ var result = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.Contains(result.Diagnostics, d => d.Contains("a3-dry-run-consumed", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Diagnostics, d => d.Contains("generic-torus-boolean-not-used", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Evidence!.Diagnostics, d => d.Contains("no-brep-emission", StringComparison.OrdinalIgnoreCase));+ Assert.Contains(result.Evidence.PathEvidence.Diagnostics, d => d.Contains("descriptor-missing", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void SurfaceFeatureEvidence_InvalidDescriptor_FailsFromPlannerOrDryRun()+ {+ var descriptor = new RoundGrooveFeatureDescriptor("g5", "base.top_face", SurfacePatchFamily.Planar, SurfaceFeaturePathKind.CircleOnPlane, SurfaceFeatureDirection.Remove, 0d, 3d, -0.1d, true);++ var result = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.False(result.Success);+ Assert.Equal(SurfaceFeatureEvidenceStatus.Invalid, result.Status);+ Assert.Null(result.Evidence);+ }++ [Fact]+ public void SurfaceFeatureEvidence_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 = SurfaceFeatureEvidenceGenerator.Generate(descriptor);++ Assert.False(result.Success);+ Assert.Equal(SurfaceFeatureEvidenceStatus.Forge, result.Status);+ Assert.False(result.MaterializationClaimed);+ Assert.Null(result.Evidence);+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureEvidenceGenerator.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureEvidenceGenerator.csnew file mode 100644index 00000000..c573d020--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFeatureEvidenceGenerator.cs@@ -0,0 +1,203 @@+namespace Aetheris.Kernel.Firmament.Execution;++internal enum SurfaceFeatureEvidenceStatus+{+ Planned,+ Deferred,+ Forge,+ Unsupported,+ Invalid+}++internal enum SurfaceFeatureGeometryStatus+{+ Exact,+ Deferred,+ DescriptorMissing+}++internal sealed record SurfaceFeatureEvidenceResult(+ bool Success,+ string FeatureId,+ SurfaceFeatureKind FeatureKind,+ string EvidenceKind,+ SurfaceFeatureEvidenceStatus Status,+ SurfaceFeatureCapabilityTier CapabilityTier,+ bool MaterializationClaimed,+ PlanarRoundGrooveEvidence? Evidence,+ IReadOnlyList<string> BlockingReasons,+ IReadOnlyList<string> Diagnostics);++internal sealed record PlanarRoundGrooveEvidence(+ string FeatureId,+ SurfacePatchFamily HostSurfaceFamily,+ SurfaceFeaturePathEvidence PathEvidence,+ SurfaceFeatureProfileEvidence ProfileEvidence,+ SurfaceFeatureDirection Direction,+ IReadOnlyList<SurfaceFeaturePatchRoleEvidence> PatchRoles,+ IReadOnlyList<SurfaceFeatureTrimRoleEvidence> TrimRoles,+ string ExactnessPolicy,+ string ExportPolicy,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeaturePathEvidence(+ SurfaceFeaturePathKind PathKind,+ string? Center,+ string? Normal,+ double? Radius,+ SurfaceFeatureGeometryStatus GeometryStatus,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeatureProfileEvidence(+ SurfaceFeatureProfileKind ProfileKind,+ double Radius,+ double Depth,+ double Width,+ SurfaceFeatureGeometryStatus GeometryStatus,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeaturePatchRoleEvidence(+ SurfaceFeaturePatchRole Role,+ SurfacePatchFamily SurfaceFamily,+ SurfaceFeatureCapabilityTier Capability,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFeatureTrimRoleEvidence(+ SurfaceFeatureTrimRole Role,+ TrimCurveFamily CurveFamily,+ TrimCurveCapability Capability,+ string ExactnessPolicy,+ IReadOnlyList<string> Diagnostics);++internal static class SurfaceFeatureEvidenceGenerator+{+ internal static SurfaceFeatureEvidenceResult Generate(SurfaceFeatureDescriptor descriptor)+ {+ var plan = SurfaceFeaturePlanner.Plan(descriptor);+ var dryRun = SurfaceFeatureDryRunGenerator.Generate(descriptor);+ var diagnostics = new List<string>+ {+ "evidence-only: generates structured non-emitting evidence for future surface-feature materializers.",+ "a3-dry-run-consumed: evidence generation consumes SURFACE-FEATURE-A3 dry-run output.",+ "generic-torus-boolean-not-used: evidence remains semantic surface-feature planning and dry-run driven."+ };+ diagnostics.AddRange(plan.Diagnostics);+ diagnostics.AddRange(dryRun.Diagnostics);++ if (plan.Status != SurfaceFeaturePlanningStatus.Planned || !dryRun.Success)+ {+ diagnostics.Add("planner-or-dry-run-terminal: evidence stopped because planner/dry-run did not produce a planned groove dry-run.");+ return new(+ Success: false,+ FeatureId: descriptor.FeatureId,+ FeatureKind: plan.FeatureKind,+ EvidenceKind: "none",+ Status: MapStatus(plan.Status),+ CapabilityTier: plan.CapabilityTier,+ MaterializationClaimed: false,+ Evidence: null,+ BlockingReasons: plan.BlockingReasons.Concat(dryRun.BlockingReasons).Distinct(StringComparer.Ordinal).ToArray(),+ Diagnostics: diagnostics);+ }++ if (!IsPlanarRoundGroove(descriptor, plan))+ {+ diagnostics.Add("evidence-deferred: current A4 evidence scaffold is constrained to planar round groove with remove direction.");+ return new(false, descriptor.FeatureId, plan.FeatureKind, "none", SurfaceFeatureEvidenceStatus.Deferred, SurfaceFeatureCapabilityTier.Deferred, false, null, ["evidence-scope-limited"], diagnostics);+ }++ var pathEvidence = BuildPathEvidence(descriptor);+ var profileEvidence = new SurfaceFeatureProfileEvidence(+ descriptor.ProfileKind,+ Radius: descriptor.ProfileRadius,+ Depth: descriptor.DepthOrHeight,+ Width: descriptor.ProfileRadius * 2d,+ GeometryStatus: SurfaceFeatureGeometryStatus.Exact,+ Diagnostics: ["profile-parameters-from-descriptor: circular arc radius/depth captured from validated descriptor."]);++ var patchRoles = dryRun.PatchExpectations+ .Select(p => new SurfaceFeaturePatchRoleEvidence(p.PatchRole, p.SurfaceFamily, p.Capability, p.Diagnostics))+ .ToArray();++ var trimRoles = dryRun.TrimExpectations+ .Select(t => new SurfaceFeatureTrimRoleEvidence(t.TrimRole, t.CurveFamily, t.Capability, t.ExactnessPolicy, t.Diagnostics))+ .ToArray();++ var evidenceDiagnostics = new List<string>+ {+ "no-brep-emission: evidence does not emit faces/edges/loops/coedges.",+ "materialization-not-implemented: evidence is preparatory data for future materializers only.",+ "export-policy-deferred: STEP/export exactness remains deferred to later milestones."+ };++ var evidence = new PlanarRoundGrooveEvidence(+ descriptor.FeatureId,+ SurfacePatchFamily.Planar,+ pathEvidence,+ profileEvidence,+ descriptor.Direction,+ patchRoles,+ trimRoles,+ ExactnessPolicy: "circular host trims expected exact; profile coupling may require explicit BSpline approximation policy",+ ExportPolicy: "deferred-no-export-claim",+ Diagnostics: evidenceDiagnostics);++ diagnostics.Add("surface-feature-a4-success: planar round groove evidence assembled from A2 planner and A3 dry-run contracts.");++ return new(+ Success: true,+ FeatureId: descriptor.FeatureId,+ FeatureKind: plan.FeatureKind,+ EvidenceKind: "planar-round-groove",+ Status: SurfaceFeatureEvidenceStatus.Planned,+ CapabilityTier: SurfaceFeatureCapabilityTier.CoreExact,+ MaterializationClaimed: false,+ Evidence: evidence,+ BlockingReasons: ["brep-materialization-not-implemented", "topology-emission-not-implemented", "step-exactness-not-claimed"],+ Diagnostics: diagnostics);+ }++ private static SurfaceFeaturePathEvidence BuildPathEvidence(SurfaceFeatureDescriptor descriptor)+ {+ if (descriptor.PathParameters is null)+ {+ return new(+ descriptor.PathKind,+ Center: null,+ Normal: null,+ Radius: descriptor.CenterlineRadius,+ GeometryStatus: SurfaceFeatureGeometryStatus.DescriptorMissing,+ Diagnostics:+ [+ "descriptor-missing-center-normal: path center/normal placement fields are not yet carried in SurfaceFeatureDescriptor.PathParameters.",+ "radius-from-descriptor: centerline radius is available and captured."+ ]);+ }++ return new(+ descriptor.PathKind,+ Center: descriptor.PathParameters.TryGetValue("center", out var c) ? c.ToString("0.###") : null,+ Normal: descriptor.PathParameters.TryGetValue("normal", out var n) ? n.ToString("0.###") : null,+ Radius: descriptor.CenterlineRadius,+ GeometryStatus: SurfaceFeatureGeometryStatus.Deferred,+ Diagnostics: ["path-parameter-payload-present: parameter dictionary exists but typed center/normal vector fields are deferred in A4 scaffold."]);+ }++ 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 SurfaceFeatureEvidenceStatus MapStatus(SurfaceFeaturePlanningStatus status)+ => status switch+ {+ SurfaceFeaturePlanningStatus.Planned => SurfaceFeatureEvidenceStatus.Planned,+ SurfaceFeaturePlanningStatus.Deferred => SurfaceFeatureEvidenceStatus.Deferred,+ SurfaceFeaturePlanningStatus.Forge => SurfaceFeatureEvidenceStatus.Forge,+ SurfaceFeaturePlanningStatus.Unsupported => SurfaceFeatureEvidenceStatus.Unsupported,+ SurfaceFeaturePlanningStatus.Invalid => SurfaceFeatureEvidenceStatus.Invalid,+ _ => SurfaceFeatureEvidenceStatus.Unsupported+ };+}diff --git a/docs/surface-feature-a4-planar-groove-evidence.md b/docs/surface-feature-a4-planar-groove-evidence.mdnew file mode 100644index 00000000..22438c6c--- /dev/null+++ b/docs/surface-feature-a4-planar-groove-evidence.md@@ -0,0 +1,89 @@+# SURFACE-FEATURE-A4 — planar round-groove evidence model++## Purpose++SURFACE-FEATURE-A4 converts the A3 planar round-groove dry-run into structured **internal evidence objects** suitable for future materializers, while preserving strictly non-emitting behavior.++This milestone is constrained to:++- `RoundGrooveFeatureDescriptor`+- `HostSurfaceFamily = Planar`+- `PathKind = CircleOnPlane`+- `ProfileKind = CircularArc`+- `Direction = Remove`++## Evidence model++A4 introduces `SurfaceFeatureEvidenceResult` and `PlanarRoundGrooveEvidence` with support records for:++- host/path/profile evidence,+- patch-role evidence,+- trim-role evidence,+- exactness/export policy,+- blockers and diagnostics,+- `MaterializationClaimed = false`.++Evidence generation explicitly consumes:++1. `SurfaceFeaturePlanner.Plan(...)` (A2),+2. `SurfaceFeatureDryRunGenerator.Generate(...)` (A3).++If planner or dry-run does not reach planned success, A4 returns terminal/deferred evidence state and does not fabricate geometry.++## Geometry completeness and deferred fields++A4 captures available deterministic descriptor parameters:++- profile radius,+- centerline radius,+- depth/height,+- derived profile width (`2 * profileRadius`).++Current descriptor contracts do not provide typed path placement (`center`, `normal`) for circle-on-plane. A4 therefore marks path geometry status as `DescriptorMissing` and emits explicit diagnostics identifying missing fields rather than inventing values.++## Patch and trim role evidence++A4 maps A3 dry-run role outputs directly into structured evidence:++- patch roles: host-retained planar patch, groove wall, groove bottom/profile,+- trim roles: outer circular boundary, inner circular boundary, profile boundary,+- capability and exactness policies retained from A3 outputs.++## Exact vs spline/deferred policy++A4 preserves policy distinction:++- circular host trims are expected exact when circle-on-plane constraints hold,+- profile coupling can require explicit BSpline approximation policy,+- export/materialization remains deferred.++No exact STEP export claim is made.++## Non-goals preserved++A4 does not implement:++- BRep materialization,+- topology emission,+- STEP export behavior changes,+- CIR Boolean mutation,+- generic torus Boolean support,+- thread geometry,+- public CLI exposure,+- generated topology naming.++## SEM-A0 guardrails++SEM-A0 remains preserved:++- no generated topology naming,+- no selector namespace expansion,+- diagnostics/provenance remain descriptor/planning/dry-run based.++## JudgmentEngine usage decision++A4 mapping is deterministic for one constrained accepted path (planar round groove via A2+A3). No competing runtime strategy set is selected in this milestone, so `JudgmentEngine` is intentionally not used.++## Next step++Extend descriptors/planning contracts with typed circle path placement evidence (center + normal frame), then promote path geometry status from `DescriptorMissing` to exact-ready for A5 materializer preparation.