Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.1 surface patch descriptor and family registry scaffold

Yuechen Li904942a73d43
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
new file mode 100644
index 00000000..57b13591
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -0,0 +1,77 @@
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfacePatchDescriptorScaffoldTests
+{
+ [Fact]
+ public void SourceSurfaceDescriptor_Box_ProducesSixPlanarDescriptors()
+ {
+ var descriptors = Enumerable.Range(0, 6)
+ .Select(i => new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, $"box-face-{i}", Transform3D.Identity, "cir:box", nameof(Aetheris.Kernel.Core.Cir.CirBoxNode), 0, FacePatchOrientationRole.Forward))
+ .ToArray();
+
+ Assert.Equal(6, descriptors.Length);
+ Assert.All(descriptors, d => Assert.Equal(SurfacePatchFamily.Planar, d.Family));
+ Assert.All(descriptors, d => Assert.False(string.IsNullOrWhiteSpace(d.Provenance)));
+ }
+
+ [Fact]
+ public void SourceSurfaceDescriptor_Cylinder_ProducesCylindricalAndPlanarDescriptors()
+ {
+ var side = new SourceSurfaceDescriptor(SurfacePatchFamily.Cylindrical, "side", Transform3D.Identity, "cir:cylinder:side", nameof(Aetheris.Kernel.Core.Cir.CirCylinderNode), 1, FacePatchOrientationRole.Forward);
+ var top = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "cap-top", Transform3D.Identity, "cir:cylinder:cap-top", nameof(Aetheris.Kernel.Core.Cir.CirCylinderNode), 1, FacePatchOrientationRole.Forward);
+ var bottom = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "cap-bottom", Transform3D.Identity, "cir:cylinder:cap-bottom", nameof(Aetheris.Kernel.Core.Cir.CirCylinderNode), 1, FacePatchOrientationRole.Reversed);
+
+ Assert.Equal(SurfacePatchFamily.Cylindrical, side.Family);
+ Assert.Equal(SurfacePatchFamily.Planar, top.Family);
+ Assert.Equal(SurfacePatchFamily.Planar, bottom.Family);
+ }
+
+ [Fact]
+ public void SourceSurfaceDescriptor_Sphere_ProducesSphericalDescriptor()
+ {
+ var sphere = new SourceSurfaceDescriptor(SurfacePatchFamily.Spherical, "sphere", Transform3D.Identity, "cir:sphere", nameof(Aetheris.Kernel.Core.Cir.CirSphereNode), 2, FacePatchOrientationRole.Forward);
+ Assert.Equal(SurfacePatchFamily.Spherical, sphere.Family);
+ }
+
+ [Fact]
+ public void SourceSurfaceDescriptor_Torus_ProducesToroidalDescriptorUnsupportedMaterializer()
+ {
+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Toroidal, "torus", Transform3D.Identity, "cir:torus", nameof(Aetheris.Kernel.Core.Cir.CirTorusNode), 3, FacePatchOrientationRole.Forward);
+ var patch = new FacePatchDescriptor(source, [], [], FacePatchOrientationRole.Forward, "tool-surface", []);
+
+ var eval = SurfaceFamilyMaterializerRegistry.Evaluate(patch);
+
+ Assert.False(eval.IsSuccess);
+ Assert.Contains(eval.Rejections, r => r.CandidateName == "surface_family_toroidal" && r.Reason.Contains("deferred", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SurfaceFamilyRegistry_SelectsPlanarForPlanarPatch()
+ {
+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "plane", Transform3D.Identity, "cir:box", nameof(Aetheris.Kernel.Core.Cir.CirBoxNode), 0, FacePatchOrientationRole.Forward);
+ var trim = new TrimCurveDescriptor(TrimCurveFamily.Line, "edge-0", "loop:outer", 0, new ParameterInterval(0, 1), TrimCurveCapability.ExactSupported);
+ var patch = new FacePatchDescriptor(source, [trim], [], FacePatchOrientationRole.Forward, "outer", []);
+
+ var eval = SurfaceFamilyMaterializerRegistry.Evaluate(patch);
+
+ Assert.True(eval.IsSuccess);
+ Assert.Equal("surface_family_planar", eval.Selected?.Name);
+ }
+
+ [Fact]
+ public void SurfaceFamilyRegistry_RejectsWrongFamilyWithReasons()
+ {
+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Spherical, "sphere", Transform3D.Identity, "cir:sphere", nameof(Aetheris.Kernel.Core.Cir.CirSphereNode), 4, FacePatchOrientationRole.Forward);
+ var patch = new FacePatchDescriptor(source, [], [], FacePatchOrientationRole.Forward, "outer", []);
+
+ var eval = SurfaceFamilyMaterializerRegistry.Evaluate(patch);
+
+ Assert.True(eval.IsSuccess);
+ Assert.Equal("surface_family_spherical", eval.Selected?.Name);
+ Assert.Contains(eval.Rejections, r => r.CandidateName == "surface_family_planar" && r.Reason.Contains("mismatch", StringComparison.OrdinalIgnoreCase));
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
new file mode 100644
index 00000000..189f356d
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -0,0 +1,191 @@
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Judgment;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+/// <summary>
+/// CIR-F8.1 scaffold: descriptor-first path toward surface-family materialization.
+/// Existing pair-specific materializers remain compatibility/fast paths.
+/// </summary>
+internal enum SurfacePatchFamily
+{
+ Planar,
+ Cylindrical,
+ Conical,
+ Spherical,
+ Toroidal,
+ Spline,
+ Prismatic,
+ Unsupported
+}
+
+internal enum TrimCurveFamily
+{
+ Line,
+ Circle,
+ Ellipse,
+ BSpline,
+ Polyline,
+ AlgebraicImplicit,
+ Unsupported
+}
+
+internal enum TrimCurveCapability
+{
+ ExactSupported,
+ SpecialCaseOnly,
+ Deferred,
+ Unsupported
+}
+
+internal enum FacePatchOrientationRole
+{
+ Unknown,
+ Forward,
+ Reversed
+}
+
+internal sealed record SourceSurfaceDescriptor(
+ SurfacePatchFamily Family,
+ string? ParameterPayloadReference,
+ Transform3D Transform,
+ string Provenance,
+ string? OwningCirNodeKind,
+ int? ReplayOpIndex,
+ FacePatchOrientationRole OrientationRole);
+
+internal sealed record TrimCurveDescriptor(
+ TrimCurveFamily Family,
+ string? ParameterPayloadReference,
+ string Provenance,
+ int? ReplayOpIndex,
+ ParameterInterval? Domain,
+ TrimCurveCapability Capability);
+
+internal sealed record FacePatchDescriptor(
+ SourceSurfaceDescriptor SourceSurface,
+ IReadOnlyList<TrimCurveDescriptor> OuterLoop,
+ IReadOnlyList<IReadOnlyList<TrimCurveDescriptor>> InnerLoops,
+ FacePatchOrientationRole Orientation,
+ string Role,
+ IReadOnlyList<string> AdjacencyHints);
+
+internal sealed record SurfaceMaterializerAdmissibility(
+ bool IsAdmissible,
+ string Reason,
+ double Score,
+ bool IsDeferred = false);
+
+internal interface ISurfaceFamilyMaterializer
+{
+ SurfacePatchFamily Family { get; }
+ string Name { get; }
+ SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch);
+}
+
+internal static class SurfaceFamilyMaterializerRegistry
+{
+ private static readonly JudgmentEngine<FacePatchDescriptor> Engine = new();
+ private static readonly ISurfaceFamilyMaterializer[] Materializers =
+ [
+ new PlanarSurfaceMaterializer(),
+ new CylindricalSurfaceMaterializer(),
+ new ConicalSurfaceMaterializer(),
+ new SphericalSurfaceMaterializer(),
+ new ToroidalSurfaceMaterializer(),
+ new SplineSurfaceMaterializer()
+ ];
+
+ internal static SurfaceFamilyMaterializerEvaluation Evaluate(FacePatchDescriptor patch)
+ {
+ var evaluations = Materializers.Select(m => new { Materializer = m, Admissibility = m.Evaluate(patch) }).ToArray();
+ var candidates = evaluations.Select((entry, i) => new JudgmentCandidate<FacePatchDescriptor>(entry.Materializer.Name, _ => entry.Admissibility.IsAdmissible, _ => entry.Admissibility.Score, _ => entry.Admissibility.Reason, i)).ToArray();
+ var judgment = Engine.Evaluate(patch, candidates);
+ var rejected = evaluations
+ .Where(e => !e.Admissibility.IsAdmissible)
+ .Select(e => new JudgmentRejection(e.Materializer.Name, e.Admissibility.Reason))
+ .ToArray();
+ if (!judgment.IsSuccess)
+ {
+ return new(null, false, "No surface-family materializer admitted patch.", rejected);
+ }
+
+ return new(Materializers.Single(m => m.Name == judgment.Selection!.Value.Candidate.Name), true, "admissible", rejected);
+ }
+}
+
+internal sealed record SurfaceFamilyMaterializerEvaluation(
+ ISurfaceFamilyMaterializer? Selected,
+ bool IsSuccess,
+ string Message,
+ IReadOnlyList<JudgmentRejection> Rejections);
+
+internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Planar;
+ public string Name => "surface_family_planar";
+
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ {
+ if (patch.SourceSurface.Family != SurfacePatchFamily.Planar) return new(false, "Source surface family mismatch.", 0d);
+ if (patch.OuterLoop.Any(t => t.Capability != TrimCurveCapability.ExactSupported) || patch.InnerLoops.SelectMany(l => l).Any(t => t.Capability != TrimCurveCapability.ExactSupported))
+ {
+ return new(false, "Trim capability requires exact-supported curves for planar scaffold.", 0d);
+ }
+
+ return new(true, "admissible", 10d);
+ }
+}
+
+internal sealed class CylindricalSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Cylindrical;
+ public string Name => "surface_family_cylindrical";
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ => patch.SourceSurface.Family == SurfacePatchFamily.Cylindrical
+ && patch.OuterLoop.All(t => t.Capability == TrimCurveCapability.ExactSupported)
+ ? new(true, "admissible", 9d)
+ : new(false, "Requires cylindrical source and exact-supported trims.", 0d);
+}
+
+internal sealed class ConicalSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Conical;
+ public string Name => "surface_family_conical";
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ => patch.SourceSurface.Family == SurfacePatchFamily.Conical
+ ? new(false, "Conical descriptor family recognized, materialization deferred in CIR-F8.1.", 1d, IsDeferred: true)
+ : new(false, "Source surface family mismatch.", 0d);
+}
+
+internal sealed class SphericalSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Spherical;
+ public string Name => "surface_family_spherical";
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ => patch.SourceSurface.Family == SurfacePatchFamily.Spherical
+ && patch.OuterLoop.All(t => t.Capability == TrimCurveCapability.ExactSupported)
+ ? new(true, "admissible", 8d)
+ : new(false, "Requires spherical source and exact-supported trims.", 0d);
+}
+
+internal sealed class ToroidalSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Toroidal;
+ public string Name => "surface_family_toroidal";
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ => patch.SourceSurface.Family == SurfacePatchFamily.Toroidal
+ ? new(false, "Toroidal descriptor family recognized, materialization deferred in CIR-F8.1.", 1d, IsDeferred: true)
+ : new(false, "Source surface family mismatch.", 0d);
+}
+
+internal sealed class SplineSurfaceMaterializer : ISurfaceFamilyMaterializer
+{
+ public SurfacePatchFamily Family => SurfacePatchFamily.Spline;
+ public string Name => "surface_family_spline";
+ public SurfaceMaterializerAdmissibility Evaluate(FacePatchDescriptor patch)
+ => patch.SourceSurface.Family == SurfacePatchFamily.Spline
+ ? new(false, "Spline descriptor family recognized, materialization deferred in CIR-F8.1.", 1d, IsDeferred: true)
+ : new(false, "Source surface family mismatch.", 0d);
+}
diff --git a/docs/cir-f81-surface-patch-descriptors.md b/docs/cir-f81-surface-patch-descriptors.md
new file mode 100644
index 00000000..5862b78e
--- /dev/null
+++ b/docs/cir-f81-surface-patch-descriptors.md
@@ -0,0 +1,94 @@
+# CIR-F8.1 — Surface patch descriptor + surface-family materializer registry scaffold
+
+## Why this scaffold exists
+
+CIR-F0–F7 proved replay-guided CIR→BRep rematerialization for selected pair-specific patterns (`subtract(box,cylinder)`, `subtract(box,box)`) and explicit unsupported diagnostics for torus pressure tests. CIR-F8.1 introduces the architecture shape needed to avoid pair-specific materializer explosion.
+
+Instead of growing:
+
+- `subtract_box_cylinder`
+- `subtract_box_box`
+- `subtract_box_sphere`
+- `subtract_box_torus`
+
+the forward path is descriptor-fed surface-family materializers:
+
+- `PlanarSurfaceMaterializer`
+- `CylindricalSurfaceMaterializer`
+- `ConicalSurfaceMaterializer`
+- `SphericalSurfaceMaterializer`
+- `ToroidalSurfaceMaterializer`
+- `SplineSurfaceMaterializer`
+
+Pair-specific materializers remain intact as fast-path/compatibility strategies in `CirBrepMaterializer` during this transition.
+
+## Descriptor model introduced
+
+CIR-F8.1 adds internal scaffold descriptors:
+
+- `SourceSurfaceDescriptor`
+ - surface family
+ - parameter payload reference
+ - transform
+ - provenance and replay op reference
+ - owning CIR node kind
+ - orientation role
+- `TrimCurveDescriptor`
+ - curve family
+ - payload reference
+ - provenance and replay op reference
+ - domain interval
+ - capability tag
+- `FacePatchDescriptor`
+ - source surface descriptor
+ - outer/inner trim loops
+ - orientation and role
+ - adjacency hints
+
+## Family and capability enums
+
+Surface families:
+
+- `Planar`, `Cylindrical`, `Conical`, `Spherical`, `Toroidal`, `Spline`, `Prismatic`, `Unsupported`
+
+Trim curve families:
+
+- `Line`, `Circle`, `Ellipse`, `BSpline`, `Polyline`, `AlgebraicImplicit`, `Unsupported`
+
+Trim capability tags:
+
+- `ExactSupported`, `SpecialCaseOnly`, `Deferred`, `Unsupported`
+
+## Registry skeleton
+
+`SurfaceFamilyMaterializerRegistry` is validation/admission-only in CIR-F8.1.
+
+- Accepts a `FacePatchDescriptor`.
+- Runs family materializer candidates through `JudgmentEngine`.
+- Returns selected candidate or structured rejection diagnostics.
+- Does **not** emit BRep topology/geometry in this milestone.
+
+## Initial family readiness in this milestone
+
+- Planar: admissible for planar patches with exact-supported trims.
+- Cylindrical: admissible for cylindrical patches with exact-supported trims.
+- Spherical: admissible for spherical patches with exact-supported trims.
+- Conical: recognized, explicitly deferred.
+- Toroidal: recognized, explicitly deferred.
+- Spline: recognized, explicitly deferred.
+
+## SEM-A0 guardrails
+
+No topology naming generation is introduced. Descriptors carry provenance handles only. This preserves SEM-A0 constraints while improving diagnosability.
+
+## Behavior impact
+
+No production CIR→BRep behavior changes in CIR-F8.1:
+
+- existing pair-specific strategy registry remains unchanged,
+- no new pair-specific materializers were added,
+- no STEP export surface/curve behavior was modified.
+
+## Next step (recommended CIR-F8.2)
+
+Add centralized trim capability matrix (surface-family × trim-curve family × status), then connect descriptor extraction from real CIR + replay operations before any BRep emission from surface-family handlers.