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