Skip to content

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