Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add explicit fillet contact graph topology validation

Yuechen Li003e15f59cda
diff --git a/Aetheris.Kernel.Firmament.Tests/Integration/ProfileBoundaryChamferTests.cs b/Aetheris.Kernel.Firmament.Tests/Integration/ProfileBoundaryChamferTests.cs
index bef8e7b6..a4e53d39 100644
--- a/Aetheris.Kernel.Firmament.Tests/Integration/ProfileBoundaryChamferTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/Integration/ProfileBoundaryChamferTests.cs
@@ -208,6 +208,92 @@ public sealed class ProfileBoundaryChamferTests
Assert.Contains("ProfileBoundaryFilletJunctionTopologyNotMaterialized", ProfileFilletShellPlanner.TryPlan(Profile(), threeTarget!, threeRadius, threeClearance).Diagnostics);
}
+ [Fact]
+ public void StraightRoll_ExposesOnePreallocatedSideContactWithOppositeFaceUses()
+ {
+ const string source = "Modify Body { EdgeFinish Round { Target: Bracket.Outer.South On: Top Kind: Fillet Radius: 2mm EndClearance: 3mm } }";
+ Assert.True(ProfileBoundaryChamferSourceBinder.TryBindFillet(source, Profile(), "Bracket", out var target, out var radius, out var clearance, out var diagnostic), diagnostic);
+ var m1 = ProfileStraightEdgeFilletPlanner.TryPlan(Profile(), target!, radius, clearance);
+ var roll = Assert.IsType<StraightFilletRollComponent>(m1.Plan!.RollComponent);
+ var extracted = ProfileFilletSideContactExtractor.ExtractStraightRoll(roll);
+ var plan = new ProfileFilletContactShellPlan(target!, [], [], [], new Dictionary<string, IReadOnlyList<ProfileFilletContactBoundary>>(), ["test"])
+ {
+ SideContactChains = [extracted.Chain],
+ ContactEdgeIncidence = [extracted.Incidence],
+ ContactVertexIncidence = extracted.Vertices
+ };
+
+ var validation = ProfileFilletContactGraphValidator.Validate(plan);
+
+ Assert.True(validation.Succeeded, string.Join(Environment.NewLine, validation.Diagnostics));
+ Assert.Equal(ProfileFilletSideContactRole.RollSideContact, Assert.IsType<ProfileFilletSideContactEdge>(Assert.Single(extracted.Chain.OrderedContacts)).Role);
+ Assert.NotEqual(extracted.Incidence.FaceUseA.TraversesWithCurveParameter, extracted.Incidence.FaceUseB.TraversesWithCurveParameter);
+ }
+
+ [Fact]
+ public void ContactGraph_ReportsThePlannedIncidenceFailureInsteadOfDeferringToTheManifoldGate()
+ {
+ const string source = "Modify Body { EdgeFinish Round { Target: Bracket.Outer.South On: Top Kind: Fillet Radius: 2mm EndClearance: 3mm } }";
+ Assert.True(ProfileBoundaryChamferSourceBinder.TryBindFillet(source, Profile(), "Bracket", out var target, out var radius, out var clearance, out var diagnostic), diagnostic);
+ var roll = Assert.IsType<StraightFilletRollComponent>(ProfileStraightEdgeFilletPlanner.TryPlan(Profile(), target!, radius, clearance).Plan!.RollComponent);
+ var extracted = ProfileFilletSideContactExtractor.ExtractStraightRoll(roll);
+ var invalidIncidence = extracted.Incidence with { FaceUseB = extracted.Incidence.FaceUseB with { TraversesWithCurveParameter = true } };
+ var plan = new ProfileFilletContactShellPlan(target!, [], [], [], new Dictionary<string, IReadOnlyList<ProfileFilletContactBoundary>>(), ["test"])
+ {
+ SideContactChains = [extracted.Chain],
+ ContactEdgeIncidence = [invalidIncidence],
+ ContactVertexIncidence = extracted.Vertices
+ };
+
+ var validation = ProfileFilletContactGraphValidator.Validate(plan);
+
+ Assert.False(validation.Succeeded);
+ Assert.Contains($"ProfileFilletContactOrientationConflict:edge={invalidIncidence.EdgeId}", validation.Diagnostics);
+ }
+
+ [Fact]
+ public void ConvexSharpSide_RequiresAnOrderedRollAndSupportChainWithSharedIncidence()
+ {
+ const string source = "Selection Corner { Source: Bracket.Outer.[South, East] Require: ConnectedChain } Modify Body { EdgeFinish Round { Target: Corner On: Top Kind: Fillet Radius: 2mm EndClearance: 3mm } }";
+ Assert.True(ProfileBoundaryChamferSourceBinder.TryBindFillet(source, Profile(), "Bracket", out var target, out var radius, out var clearance, out var diagnostic), diagnostic);
+ var m2 = ProfileFilletShellPlanner.TryPlan(Profile(), target!, radius, clearance);
+ var extracted = ProfileFilletSideContactExtractor.ExtractConvexSharp(m2.Plan!);
+ var chain = extracted.Chains[0];
+ var plan = new ProfileFilletContactShellPlan(target!, [], [], [], new Dictionary<string, IReadOnlyList<ProfileFilletContactBoundary>>(), ["test"])
+ {
+ SideContactChains = extracted.Chains,
+ ContactEdgeIncidence = extracted.EdgeIncidence,
+ ContactVertexIncidence = extracted.VertexIncidence
+ };
+
+ var validation = ProfileFilletContactGraphValidator.Validate(plan);
+
+ Assert.True(validation.Succeeded, string.Join(Environment.NewLine, validation.Diagnostics));
+ Assert.Equal([ProfileFilletSideContactRole.RollSideContact, ProfileFilletSideContactRole.JunctionSupportContact], chain.OrderedContacts.Select(contact => contact.Role));
+ }
+
+ [Fact]
+ public void ReflexNotch_UsesAPointContactInsteadOfAZeroLengthSupportEdge()
+ {
+ const string source = "Selection Notch { Source: Bracket.Outer.[Inner, Upright] Require: ConnectedChain } Modify Body { EdgeFinish Round { Target: Notch On: Top Kind: Fillet Radius: 2mm } }";
+ Assert.True(ProfileBoundaryChamferSourceBinder.TryBindFillet(source, LProfile(), "Bracket", out var target, out var radius, out var clearance, out var diagnostic), diagnostic);
+ var m3 = ProfileFilletShellPlanner.TryPlan(LProfile(), target!, radius, clearance);
+ var extracted = ProfileFilletSideContactExtractor.ExtractExactRollingReflex(m3.Plan!);
+ var chain = extracted.Chains[0];
+ var plan = new ProfileFilletContactShellPlan(target!, [], [], [], new Dictionary<string, IReadOnlyList<ProfileFilletContactBoundary>>(), ["test"])
+ {
+ SideContactChains = extracted.Chains,
+ ContactEdgeIncidence = extracted.EdgeIncidence,
+ ContactVertexIncidence = extracted.VertexIncidence
+ };
+
+ var validation = ProfileFilletContactGraphValidator.Validate(plan);
+
+ Assert.True(validation.Succeeded, string.Join(Environment.NewLine, validation.Diagnostics));
+ Assert.Single(chain.OrderedContacts.OfType<ProfileFilletSideContactVertex>());
+ Assert.DoesNotContain(plan.ContactEdgeIncidence, contract => contract.StartVertexId == contract.EndVertexId);
+ }
+
[Fact]
public void CurvedWholeLoopChamferMaterializesThroughTheMixedPlaneConeShell()
{
diff --git a/Aetheris.Kernel.Firmament/Materializer/ProfileFilletContactShellPlan.cs b/Aetheris.Kernel.Firmament/Materializer/ProfileFilletContactShellPlan.cs
index 74d949e9..a0715098 100644
--- a/Aetheris.Kernel.Firmament/Materializer/ProfileFilletContactShellPlan.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/ProfileFilletContactShellPlan.cs
@@ -30,7 +30,18 @@ public sealed record ProfileFilletContactShellPlan(
IReadOnlyList<ProfileFilletContactBoundary> OrderedInterfaces,
IReadOnlyList<ProfileFilletContactBoundary> OrderedCapContacts,
IReadOnlyDictionary<string, IReadOnlyList<ProfileFilletContactBoundary>> SideContactsBySource,
- IReadOnlyList<string> Provenance);
+ IReadOnlyList<string> Provenance)
+{
+ /// <summary>
+ /// Parent-side ownership is deliberately separate from the component contact
+ /// list. A sharp component can therefore contribute more than one boundary
+ /// to one surviving source side without asking an emitter to rediscover it.
+ /// </summary>
+ public IReadOnlyList<ProfileFilletSideContactChain> SideContactChains { get; init; } = [];
+ public IReadOnlyList<ProfileFilletContactEdgeIncidenceContract> ContactEdgeIncidence { get; init; } = [];
+ public IReadOnlyList<ProfileFilletContactVertexIncidence> ContactVertexIncidence { get; init; } = [];
+ public IReadOnlyList<ProfileFilletSourceSideTrimPlan> SourceSideTrims { get; init; } = [];
+}
public sealed record ProfileFilletComponentContactContract(
string ComponentId,
@@ -43,8 +54,371 @@ public sealed record ProfileFilletComponentContactContract(
IReadOnlyList<string> SemanticDescendants,
IReadOnlyList<string> Provenance);
+/// <summary>Semantic role of a parent-side boundary contributed by a fillet component.</summary>
+public enum ProfileFilletSideContactRole
+{
+ RollSideContact,
+ JunctionSupportContact,
+ JunctionSideContact,
+ RetainedSharpContact,
+ TransitionContact
+}
+
+/// <summary>
+/// One item in an ordered parent-side chain. Edge and vertex contacts are
+/// distinct so a collapsed reflex notch cannot be smuggled through as a
+/// zero-length curve.
+/// </summary>
+public abstract record ProfileFilletSideContactElement(
+ string StableId,
+ string ComponentId,
+ string SourceSideId,
+ ProfileFilletSideContactRole Role,
+ string ExpectedOppositeFaceOwner,
+ int Position,
+ string? PredecessorId,
+ string? SuccessorId,
+ IReadOnlyList<string> Provenance);
+
+public sealed record ProfileFilletSideContactEdge(
+ string StableId,
+ string ComponentId,
+ string SourceSideId,
+ ProfileFilletSideContactRole Role,
+ CurveGeometry Curve,
+ ParameterInterval Trim,
+ string StartVertexId,
+ string EndVertexId,
+ bool TraversesWithCurveParameter,
+ string ExpectedOppositeFaceOwner,
+ int Position,
+ string? PredecessorId,
+ string? SuccessorId,
+ IReadOnlyList<string> Provenance)
+ : ProfileFilletSideContactElement(StableId, ComponentId, SourceSideId, Role,
+ ExpectedOppositeFaceOwner, Position, PredecessorId, SuccessorId, Provenance);
+
+public sealed record ProfileFilletSideContactVertex(
+ string StableId,
+ string ComponentId,
+ string SourceSideId,
+ ProfileFilletSideContactRole Role,
+ string VertexId,
+ string ExpectedOppositeFaceOwner,
+ int Position,
+ string? PredecessorId,
+ string? SuccessorId,
+ IReadOnlyList<string> Provenance)
+ : ProfileFilletSideContactElement(StableId, ComponentId, SourceSideId, Role,
+ ExpectedOppositeFaceOwner, Position, PredecessorId, SuccessorId, Provenance);
+
+/// <summary>Source-order upper boundary of one parent-owned source-side fragment group.</summary>
+public sealed record ProfileFilletSideContactChain(
+ string SourceSideId,
+ string StartVertexId,
+ string EndVertexId,
+ bool TraversesWithSourceOrder,
+ IReadOnlyList<ProfileFilletSideContactElement> OrderedContacts,
+ IReadOnlyList<string> Provenance);
+
+/// <summary>One planned use of a contact edge by a face loop.</summary>
+public sealed record ProfileFilletContactFaceUse(string FaceOwner, bool TraversesWithCurveParameter);
+
+/// <summary>
+/// Allocated before B-rep emission. Both intended face uses refer to this one
+/// identity; independent emitters are never allowed to allocate coincident
+/// support edges.
+/// </summary>
+public sealed record ProfileFilletContactEdgeIncidenceContract(
+ string EdgeId,
+ CurveGeometry Curve,
+ ParameterInterval Trim,
+ string StartVertexId,
+ string EndVertexId,
+ ProfileFilletContactFaceUse FaceUseA,
+ ProfileFilletContactFaceUse FaceUseB,
+ ProfileFilletSideContactRole Role,
+ IReadOnlyList<string> Provenance);
+
+/// <summary>Explicit non-welded vertex incidence, including point-only contacts.</summary>
+public sealed record ProfileFilletContactVertexIncidence(
+ string VertexId,
+ Point3D Point,
+ IReadOnlyList<string> IncidentEdgeIds,
+ IReadOnlyList<string> IncidentFaceOwners,
+ string SourceSemanticIdentity,
+ IReadOnlyList<string> Provenance);
+
+/// <summary>
+/// A source segment can materialize as several planar/analytic side fragments
+/// while retaining the one source-side semantic owner.
+/// </summary>
+public sealed record ProfileFilletSideFaceFragmentPlan(
+ string StableId,
+ string SourceSideId,
+ int FragmentIndex,
+ string SupportSurface,
+ IReadOnlyList<string> OrderedBoundaryEdgeIds,
+ IReadOnlyList<string> SemanticDescendants,
+ IReadOnlyList<string> Provenance);
+
+public sealed record ProfileFilletSourceSideTrimPlan(
+ string SourceSideId,
+ IReadOnlyList<ProfileFilletSideFaceFragmentPlan> Fragments,
+ IReadOnlyList<string> SharedContactEdgeIds,
+ IReadOnlyList<string> Provenance);
+
+public sealed record ProfileFilletContactGraphValidationResult(bool Succeeded, IReadOnlyList<string> Diagnostics);
+
+public sealed record ProfileFilletSideContactExtraction(
+ IReadOnlyList<ProfileFilletSideContactChain> Chains,
+ IReadOnlyList<ProfileFilletContactEdgeIncidenceContract> EdgeIncidence,
+ IReadOnlyList<ProfileFilletContactVertexIncidence> VertexIncidence);
+
public sealed record ProfileFilletContactShellPlanResult(bool Succeeded, ProfileFilletContactShellPlan? Plan, IReadOnlyList<string> Diagnostics);
+/// <summary>
+/// Validates topology ownership while names are still planned identities. This
+/// is intentionally stricter than the eventual manifold gate: the latter can
+/// say only that an emitted edge is bad, whereas this identifies the missing
+/// side/junction owner that caused it.
+/// </summary>
+public static class ProfileFilletContactGraphValidator
+{
+ public static ProfileFilletContactGraphValidationResult Validate(ProfileFilletContactShellPlan plan)
+ {
+ ArgumentNullException.ThrowIfNull(plan);
+ var diagnostics = new List<string>();
+ var contacts = plan.SideContactChains.SelectMany(chain => chain.OrderedContacts).ToArray();
+ var contactEdges = contacts.OfType<ProfileFilletSideContactEdge>().ToArray();
+ var edgeContracts = plan.ContactEdgeIncidence
+ .GroupBy(contract => contract.EdgeId, StringComparer.Ordinal)
+ .ToDictionary(group => group.Key, group => group.First(), StringComparer.Ordinal);
+
+ foreach (var chain in plan.SideContactChains)
+ {
+ if (chain.OrderedContacts.Count == 0)
+ {
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:reason=empty");
+ continue;
+ }
+
+ for (var index = 0; index < chain.OrderedContacts.Count; index++)
+ {
+ var contact = chain.OrderedContacts[index];
+ var predecessor = index == 0 ? null : chain.OrderedContacts[index - 1].StableId;
+ var successor = index == chain.OrderedContacts.Count - 1 ? null : chain.OrderedContacts[index + 1].StableId;
+ if (contact.Position != index || contact.PredecessorId != predecessor || contact.SuccessorId != successor)
+ diagnostics.Add($"ProfileFilletSideContactChainOutOfOrder:source={chain.SourceSideId}:contact={contact.StableId}");
+ }
+
+ var first = chain.OrderedContacts[0];
+ var last = chain.OrderedContacts[^1];
+ if (first is ProfileFilletSideContactEdge firstEdge && firstEdge.StartVertexId != chain.StartVertexId)
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:contact={first.StableId}:at=start");
+ if (last is ProfileFilletSideContactEdge lastEdge && lastEdge.EndVertexId != chain.EndVertexId)
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:contact={last.StableId}:at=end");
+ if (first is ProfileFilletSideContactVertex firstVertex && firstVertex.VertexId != chain.StartVertexId)
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:contact={first.StableId}:at=start");
+ if (last is ProfileFilletSideContactVertex lastVertex && lastVertex.VertexId != chain.EndVertexId)
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:contact={last.StableId}:at=end");
+
+ for (var index = 0; index < chain.OrderedContacts.Count - 1; index++)
+ {
+ var left = EndVertex(chain.OrderedContacts[index]);
+ var right = StartVertex(chain.OrderedContacts[index + 1]);
+ if (left != right)
+ diagnostics.Add($"ProfileFilletSideContactChainOpen:source={chain.SourceSideId}:between={chain.OrderedContacts[index].StableId}->{chain.OrderedContacts[index + 1].StableId}");
+ }
+ }
+
+ foreach (var edge in contactEdges)
+ {
+ if (edge.StartVertexId == edge.EndVertexId)
+ diagnostics.Add($"ProfileFilletDuplicateSupportEdge:edge={edge.StableId}:reason=zero-length-edge-contact");
+ if (!edgeContracts.TryGetValue(edge.StableId, out var contract))
+ diagnostics.Add($"ProfileFilletContactEdgeMissingSecondFace:edge={edge.StableId}:reason=no-incidence-contract");
+ else if (contract.StartVertexId != edge.StartVertexId || contract.EndVertexId != edge.EndVertexId)
+ diagnostics.Add($"ProfileFilletSideContactChainOutOfOrder:source={edge.SourceSideId}:contact={edge.StableId}:reason=contract-endpoints");
+ }
+
+ foreach (var contract in plan.ContactEdgeIncidence)
+ {
+ if (contract.StartVertexId == contract.EndVertexId)
+ diagnostics.Add($"ProfileFilletDuplicateSupportEdge:edge={contract.EdgeId}:reason=zero-length-edge-contract");
+ if (contract.FaceUseA.FaceOwner == contract.FaceUseB.FaceOwner)
+ diagnostics.Add($"ProfileFilletContactEdgeOverSubscribed:edge={contract.EdgeId}:reason=non-distinct-face-owners");
+ if (contract.FaceUseA.TraversesWithCurveParameter == contract.FaceUseB.TraversesWithCurveParameter)
+ diagnostics.Add($"ProfileFilletContactOrientationConflict:edge={contract.EdgeId}");
+ }
+
+ foreach (var duplicate in plan.ContactEdgeIncidence.GroupBy(contract => contract.EdgeId, StringComparer.Ordinal).Where(group => group.Count() != 1))
+ diagnostics.Add($"ProfileFilletContactEdgeOverSubscribed:edge={duplicate.Key}:reason=duplicate-edge-id");
+
+ foreach (var duplicate in contactEdges
+ .Where(edge => edge.Role == ProfileFilletSideContactRole.JunctionSupportContact)
+ .GroupBy(edge => (edge.SourceSideId, A: string.CompareOrdinal(edge.StartVertexId, edge.EndVertexId) < 0 ? edge.StartVertexId : edge.EndVertexId, B: string.CompareOrdinal(edge.StartVertexId, edge.EndVertexId) < 0 ? edge.EndVertexId : edge.StartVertexId))
+ .Where(group => group.Count() > 1))
+ diagnostics.Add($"ProfileFilletDuplicateSupportEdge:source={duplicate.Key.SourceSideId}:vertices={duplicate.Key.A}->{duplicate.Key.B}");
+
+ var knownEdges = plan.ContactEdgeIncidence.Select(contract => contract.EdgeId).ToHashSet(StringComparer.Ordinal);
+ foreach (var vertex in plan.ContactVertexIncidence)
+ foreach (var edgeId in vertex.IncidentEdgeIds)
+ if (!knownEdges.Contains(edgeId))
+ diagnostics.Add($"ProfileFilletContactEdgeMissingSecondFace:edge={edgeId}:vertex={vertex.VertexId}:reason=vertex-references-unknown-edge");
+
+ return new(diagnostics.Count == 0, diagnostics);
+ }
+
+ private static string StartVertex(ProfileFilletSideContactElement contact) => contact switch
+ {
+ ProfileFilletSideContactEdge edge => edge.StartVertexId,
+ ProfileFilletSideContactVertex vertex => vertex.VertexId,
+ _ => throw new NotSupportedException($"Unknown contact type {contact.GetType().Name}.")
+ };
+
+ private static string EndVertex(ProfileFilletSideContactElement contact) => contact switch
+ {
+ ProfileFilletSideContactEdge edge => edge.EndVertexId,
+ ProfileFilletSideContactVertex vertex => vertex.VertexId,
+ _ => throw new NotSupportedException($"Unknown contact type {contact.GetType().Name}.")
+ };
+}
+
+/// <summary>Extracts the reusable M1 roll-side contact before any face is emitted.</summary>
+public static class ProfileFilletSideContactExtractor
+{
+ public static (ProfileFilletSideContactChain Chain, ProfileFilletContactEdgeIncidenceContract Incidence, IReadOnlyList<ProfileFilletContactVertexIncidence> Vertices)
+ ExtractStraightRoll(StraightFilletRollComponent roll)
+ {
+ ArgumentNullException.ThrowIfNull(roll);
+ var startVertex = $"{roll.StableId}:side:start";
+ var endVertex = $"{roll.StableId}:side:end";
+ var edgeId = $"{roll.StableId}:side-contact";
+ var length = (roll.SideContactEnd - roll.SideContactStart).Length;
+ if (length <= 1e-8) throw new InvalidOperationException($"ProfileFilletSideContactZeroLength:{roll.StableId}");
+ var curve = CurveGeometry.FromLine(new Line3Curve(roll.SideContactStart, Direction3D.Create(roll.SideContactEnd - roll.SideContactStart)));
+ var sourceFace = $"source-side:{roll.SourceStableId}:fragment:0";
+ var rollFace = $"fillet-component:{roll.StableId}";
+ var edge = new ProfileFilletSideContactEdge(edgeId, roll.StableId, roll.SourceStableId,
+ ProfileFilletSideContactRole.RollSideContact, curve, new ParameterInterval(0d, length), startVertex, endVertex, true,
+ rollFace, 0, null, null, ["StraightFilletRollComponent", "ExactLine", "ParentSide"]);
+ var chain = new ProfileFilletSideContactChain(roll.SourceStableId, startVertex, endVertex, true, [edge], ["M1", "SourceOrder"]);
+ var incidence = new ProfileFilletContactEdgeIncidenceContract(edgeId, curve, edge.Trim, startVertex, endVertex,
+ new ProfileFilletContactFaceUse(sourceFace, true), new ProfileFilletContactFaceUse(rollFace, false), edge.Role,
+ ["PreallocatedSharedContactEdge", "CylinderSideContact"]);
+ return (chain, incidence,
+ [
+ new(startVertex, roll.SideContactStart, [edgeId], [sourceFace, rollFace], roll.SourceStableId, ["RollSideStart"]),
+ new(endVertex, roll.SideContactEnd, [edgeId], [sourceFace, rollFace], roll.SourceStableId, ["RollSideEnd"])
+ ]);
+ }
+
+ /// <summary>
+ /// Extracts the two real M2 source-side chains from the already-proven
+ /// roll/sphere/support topology. The support endpoint is the retained
+ /// vertical-depth vertex, not a source-offset guess.
+ /// </summary>
+ public static ProfileFilletSideContactExtraction ExtractConvexSharp(ProfileFilletShellPlan plan)
+ {
+ ArgumentNullException.ThrowIfNull(plan);
+ if (plan.Junction is not ProfileConvexSphericalJunctionPlan junction || plan.Components is not [StraightFilletRollComponent rollA, ConvexSharpFilletJunctionComponent component, StraightFilletRollComponent rollB])
+ throw new ArgumentException("ProfileFilletConvexSharpComponentsRequired", nameof(plan));
+
+ var sideA = rollA.SideContactEnd;
+ var sideB = rollB.SideContactStart;
+ // BuildSphericalJunction defines sideA = vertex + nb*r + axial*r and
+ // sideB = vertex + na*r + axial*r. Their sum minus the sphere centre
+ // is therefore exactly the support/depth vertex.
+ var depth = sideA + (sideB - junction.Center);
+ var depthId = $"{component.StableId}:vertical-depth";
+ var aExternalId = $"{rollA.StableId}:side:external";
+ var aJunctionId = $"{rollA.StableId}:side:junction";
+ var bJunctionId = $"{rollB.StableId}:side:junction";
+ var bExternalId = $"{rollB.StableId}:side:external";
+ var supportFace = $"junction-support:{component.StableId}";
+ var rollAEdge = Edge($"{rollA.StableId}:side-contact", rollA, aExternalId, aJunctionId, 0, null, $"{component.StableId}:side-a-support", ProfileFilletSideContactRole.RollSideContact, true);
+ var supportA = Edge($"{component.StableId}:side-a-support", component.StableId, rollA.SourceStableId, sideA, depth, aJunctionId, depthId, 1, rollAEdge.StableId, null, ProfileFilletSideContactRole.JunctionSupportContact, supportFace, true);
+ var supportB = Edge($"{component.StableId}:side-b-support", component.StableId, rollB.SourceStableId, depth, sideB, depthId, bJunctionId, 0, null, $"{rollB.StableId}:side-contact", ProfileFilletSideContactRole.JunctionSupportContact, supportFace, true);
+ var rollBEdge = Edge($"{rollB.StableId}:side-contact", rollB, bJunctionId, bExternalId, 1, supportB.StableId, null, ProfileFilletSideContactRole.RollSideContact, true);
+ var chainA = new ProfileFilletSideContactChain(rollA.SourceStableId, aExternalId, depthId, true, [rollAEdge, supportA], ["M2", "ConvexSphere", "SourceOrder"]);
+ var chainB = new ProfileFilletSideContactChain(rollB.SourceStableId, depthId, bExternalId, true, [supportB, rollBEdge], ["M2", "ConvexSphere", "SourceOrder"]);
+ var sourceA = SourceFace(rollA); var sourceB = SourceFace(rollB);
+ return new([chainA, chainB],
+ [
+ Incidence(rollAEdge, sourceA, RollFace(rollA)),
+ Incidence(supportA, sourceA, supportFace),
+ Incidence(supportB, sourceB, supportFace),
+ Incidence(rollBEdge, sourceB, RollFace(rollB))
+ ],
+ [
+ Vertex(aExternalId, rollA.SideContactStart, [rollAEdge.StableId], rollA.SourceStableId),
+ Vertex(aJunctionId, sideA, [rollAEdge.StableId, supportA.StableId], component.StableId),
+ Vertex(depthId, depth, [supportA.StableId, supportB.StableId], component.StableId),
+ Vertex(bJunctionId, sideB, [supportB.StableId, rollBEdge.StableId], component.StableId),
+ Vertex(bExternalId, rollB.SideContactEnd, [rollBEdge.StableId], rollB.SourceStableId)
+ ]);
+ }
+
+ /// <summary>
+ /// Extracts M3 ExactRolling. The shared notch is represented twice as a
+ /// chain endpoint but once as a planned vertex; no support edge is created.
+ /// </summary>
+ public static ProfileFilletSideContactExtraction ExtractExactRollingReflex(ProfileFilletShellPlan plan)
+ {
+ ArgumentNullException.ThrowIfNull(plan);
+ if (plan.Junction is not ProfileReflexFilletJunctionPlan junction || plan.Components is not [StraightFilletRollComponent rollA, ReflexSharpExactRollingJunctionComponent component, StraightFilletRollComponent rollB])
+ throw new ArgumentException("ProfileFilletExactRollingComponentsRequired", nameof(plan));
+
+ var notchId = $"{component.StableId}:notch";
+ var aExternalId = $"{rollA.StableId}:side:external";
+ var bExternalId = $"{rollB.StableId}:side:external";
+ var componentFace = $"fillet-component:{component.StableId}";
+ var rollAEdge = Edge($"{rollA.StableId}:side-contact", rollA, aExternalId, notchId, 0, null, $"{component.StableId}:notch:a", ProfileFilletSideContactRole.RollSideContact, true);
+ var notchA = new ProfileFilletSideContactVertex($"{component.StableId}:notch:a", component.StableId, rollA.SourceStableId,
+ ProfileFilletSideContactRole.JunctionSideContact, notchId, componentFace, 1, rollAEdge.StableId, null, ["M3", "PointContact"]);
+ var notchB = new ProfileFilletSideContactVertex($"{component.StableId}:notch:b", component.StableId, rollB.SourceStableId,
+ ProfileFilletSideContactRole.JunctionSideContact, notchId, componentFace, 0, null, $"{rollB.StableId}:side-contact", ["M3", "PointContact"]);
+ var rollBEdge = Edge($"{rollB.StableId}:side-contact", rollB, notchId, bExternalId, 1, notchB.StableId, null, ProfileFilletSideContactRole.RollSideContact, true);
+ var chainA = new ProfileFilletSideContactChain(rollA.SourceStableId, aExternalId, notchId, true, [rollAEdge, notchA], ["M3", "ExactRolling", "PointNotEdge"]);
+ var chainB = new ProfileFilletSideContactChain(rollB.SourceStableId, notchId, bExternalId, true, [notchB, rollBEdge], ["M3", "ExactRolling", "PointNotEdge"]);
+ return new([chainA, chainB],
+ [Incidence(rollAEdge, SourceFace(rollA), RollFace(rollA)), Incidence(rollBEdge, SourceFace(rollB), RollFace(rollB))],
+ [
+ Vertex(aExternalId, rollA.SideContactStart, [rollAEdge.StableId], rollA.SourceStableId),
+ Vertex(notchId, junction.VerticalNotchContact, [rollAEdge.StableId, rollBEdge.StableId], component.StableId),
+ Vertex(bExternalId, rollB.SideContactEnd, [rollBEdge.StableId], rollB.SourceStableId)
+ ]);
+ }
+
+ private static ProfileFilletSideContactEdge Edge(string edgeId, StraightFilletRollComponent roll, string startVertex, string endVertex,
+ int position, string? predecessor, string? successor, ProfileFilletSideContactRole role, bool traverses) =>
+ Edge(edgeId, roll.StableId, roll.SourceStableId, roll.SideContactStart, roll.SideContactEnd, startVertex, endVertex,
+ position, predecessor, successor, role, RollFace(roll), traverses);
+
+ private static ProfileFilletSideContactEdge Edge(string edgeId, string componentId, string sourceSideId, Point3D start, Point3D end,
+ string startVertex, string endVertex, int position, string? predecessor, string? successor, ProfileFilletSideContactRole role,
+ string oppositeFace, bool traverses)
+ {
+ var length = (end - start).Length;
+ if (length <= 1e-8) throw new InvalidOperationException($"ProfileFilletSideContactZeroLength:{edgeId}");
+ return new(edgeId, componentId, sourceSideId, role,
+ CurveGeometry.FromLine(new Line3Curve(start, Direction3D.Create(end - start))), new ParameterInterval(0d, length),
+ startVertex, endVertex, traverses, oppositeFace, position, predecessor, successor, ["ExactLine", "PreEmissionContact"]);
+ }
+
+ private static ProfileFilletContactEdgeIncidenceContract Incidence(ProfileFilletSideContactEdge edge, string sourceFace, string oppositeFace) =>
+ new(edge.StableId, edge.Curve, edge.Trim, edge.StartVertexId, edge.EndVertexId,
+ new(sourceFace, edge.TraversesWithCurveParameter), new(oppositeFace, !edge.TraversesWithCurveParameter), edge.Role,
+ ["PreallocatedSharedContactEdge"]);
+
+ private static ProfileFilletContactVertexIncidence Vertex(string id, Point3D point, IReadOnlyList<string> edges, string source) =>
+ new(id, point, edges, [], source, ["PreEmissionVertexIncidence"]);
+
+ private static string SourceFace(StraightFilletRollComponent roll) => $"source-side:{roll.SourceStableId}:fragment:0";
+ private static string RollFace(StraightFilletRollComponent roll) => $"fillet-component:{roll.StableId}";
+}
+
/// <summary>
/// Contact-only planner for the rounded, source-tangent portion of a whole
/// Profile. Sharp vertices are intentionally rejected here until their M2/M3
@@ -83,6 +457,10 @@ public static class ProfileFilletContactShellPlanner
var interfaces = new List<ProfileFilletContactBoundary>(loop.Segments.Count);
var caps = new List<ProfileFilletContactBoundary>(loop.Segments.Count);
var sides = new Dictionary<string, IReadOnlyList<ProfileFilletContactBoundary>>(StringComparer.Ordinal);
+ var sideChains = new List<ProfileFilletSideContactChain>(loop.Segments.Count);
+ var incidence = new List<ProfileFilletContactEdgeIncidenceContract>(loop.Segments.Count);
+ var vertices = new List<ProfileFilletContactVertexIncidence>(loop.Segments.Count * 2);
+ var sideTrims = new List<ProfileFilletSourceSideTrimPlan>(loop.Segments.Count);
for (var i = 0; i < loop.Segments.Count; i++)
{
@@ -102,10 +480,38 @@ public static class ProfileFilletContactShellPlanner
var next = Interface(componentId, source, ProfileFilletContactBoundaryKind.NextInterface, capEnd, end, patch, mixed.FinishSize);
components.Add(new(componentId, source, patch.SurfaceFamily, capContact, [side], previous, next, patch.SemanticDescendants, [patch.PlannerKind, "ContactContract"]));
caps.Add(capContact); interfaces.Add(previous); interfaces.Add(next); sides.Add(source, [side]);
+ var startVertexId = $"{side.StableId}:start";
+ var endVertexId = $"{side.StableId}:end";
+ var sourceFace = $"source-side:{source}:fragment:0";
+ var componentFace = $"fillet-component:{componentId}";
+ var sideEdge = new ProfileFilletSideContactEdge(side.StableId, componentId, source,
+ ProfileFilletSideContactRole.RollSideContact, side.Curve, side.Trim, startVertexId, endVertexId,
+ side.TraversesWithCurveParameter, componentFace, 0, null, null,
+ ["RoundedSourceContact", "ParentSide", .. side.Provenance]);
+ sideChains.Add(new(source, startVertexId, endVertexId, side.TraversesWithCurveParameter, [sideEdge], ["SourceOrder", "SingleContact"]));
+ incidence.Add(new(side.StableId, side.Curve, side.Trim, startVertexId, endVertexId,
+ new(sourceFace, side.TraversesWithCurveParameter), new(componentFace, !side.TraversesWithCurveParameter), sideEdge.Role,
+ ["PreallocatedSharedContactEdge", "RoundedSourceContact"]));
+ vertices.Add(new(startVertexId, side.Start, [side.StableId], [sourceFace, componentFace], source, ["SideContactStart"]));
+ vertices.Add(new(endVertexId, side.End, [side.StableId], [sourceFace, componentFace], source, ["SideContactEnd"]));
+ sideTrims.Add(new(source,
+ [new ProfileFilletSideFaceFragmentPlan($"{source}:fragment:0", source, 0, "SourceSideSupportSurface", [side.StableId],
+ [$"SideFaceFragment({source},0)"], ["RoundedSourceContact"])],
+ [side.StableId], ["ParentOwnedSide"]));
}
- return new(true, new(target, components, interfaces, caps, sides,
- ["ResolvedProfile2D", "ProfileEdgeFinishMixedShellPlan", "ContactBeforeTopology"]), []);
+ var plan = new ProfileFilletContactShellPlan(target, components, interfaces, caps, sides,
+ ["ResolvedProfile2D", "ProfileEdgeFinishMixedShellPlan", "ContactBeforeTopology"])
+ {
+ SideContactChains = sideChains,
+ ContactEdgeIncidence = incidence,
+ ContactVertexIncidence = vertices,
+ SourceSideTrims = sideTrims
+ };
+ var validation = ProfileFilletContactGraphValidator.Validate(plan);
+ return validation.Succeeded
+ ? new(true, plan, [])
+ : new(false, null, validation.Diagnostics);
}
private static ProfileFilletContactBoundary Interface(string componentId, string source, ProfileFilletContactBoundaryKind kind,
diff --git a/docs/firmament/fillet-contact-shell-composer-x6.md b/docs/firmament/fillet-contact-shell-composer-x6.md
index 37069d8b..aa360f36 100644
--- a/docs/firmament/fillet-contact-shell-composer-x6.md
+++ b/docs/firmament/fillet-contact-shell-composer-x6.md
@@ -23,6 +23,11 @@ parent-owned cap, the trimmed source sides, and the shared analytic edges. It
must not replace those contacts with offset-profile intersections, suppress
STEP preflight, introduce NURBS, or add Boolean/post-B-rep repair.
+X7 adds the missing parent-side ownership layer above these component contacts:
+an ordered `ProfileFilletSideContactChain`, explicit two-face edge-incidence
+contracts, point-only contacts, and side-fragment plan records. The graph is
+validated before B-rep allocation; see `fillet-side-contact-chain-x7.md`.
+
No whole-loop Fillet artifact is claimed yet. Existing M1/M2/M3 materializers
remain the geometry ground truth while their extracted components are promoted
to exact contact contracts.
diff --git a/docs/firmament/fillet-patch-extraction-x5.md b/docs/firmament/fillet-patch-extraction-x5.md
index 01c9c14c..e5a86586 100644
--- a/docs/firmament/fillet-patch-extraction-x5.md
+++ b/docs/firmament/fillet-patch-extraction-x5.md
@@ -57,8 +57,11 @@ fixtures retain their explicit external terminations.
## Status
-The reusable sharp component contract and regression coverage are in place.
-The seven-station closed-loop Fillet materializer, its volume assertion,
-persistent Fillet STEP artifacts, compatibility comparison, inspection JSON,
-and external-kernel smoke remain blocked on that exact global contact-boundary
-composer. No Fillet artifact is claimed by this document.
+X7 supplies the typed side-chain and pre-emission incidence layer needed by
+that composer. It establishes that M2 requires an explicit roll-plus-support
+chain and that M3 ExactRolling uses a point contact at its retained notch,
+not a zero-length support edge. The seven-station closed-loop Fillet
+materializer, its volume assertion, persistent Fillet STEP artifacts,
+compatibility comparison, inspection JSON, and external-kernel smoke remain
+blocked until all component extractors and the parent emitter consume those
+contracts. No Fillet artifact is claimed by this document.
diff --git a/docs/firmament/fillet-side-contact-chain-x7.md b/docs/firmament/fillet-side-contact-chain-x7.md
new file mode 100644
index 00000000..2cea70fe
--- /dev/null
+++ b/docs/firmament/fillet-side-contact-chain-x7.md
@@ -0,0 +1,74 @@
+# Fillet side-contact chain X7
+
+## Audit
+
+There is no recoverable parent-shell emitter diff in the current repository
+history or reflog. The evidence retained in X5/X6 and in the successful local
+M2/M3 materializers is sufficient to identify the failure class: adapting the
+Chamfer parent-side loop gave each source side one coarse contact, while sharp
+junctions have additional ownership boundaries. That makes the parent side
+skip a junction support boundary or allocate a coincident replacement. The
+result reaches the manifold gate with an edge used by one face or by three
+faces; it is not a surface-family or STEP `same_sense` problem.
+
+The local M2 emitter makes the ownership explicit:
+
+- source side A owns its cylinder-side contact and the A-side support edge;
+- source side B owns its cylinder-side contact and the B-side support edge;
+- the convex-sphere patch owns its two sphere-to-roll seams;
+- the planar junction-support face owns the opposite uses of the support
+ boundaries.
+
+The M3 ExactRolling emitter differs materially. Its two cylindrical side
+contacts meet at `junction-vertical-notch`; the horn torus has a point
+incidence there. There is no non-degenerate side-support edge at that point.
+Representing it as one would create a zero-length edge and is forbidden.
+`SphereSeamCompatibility` remains a separate component topology: its support
+contacts must be supplied by that component, never copied from the torus case.
+
+## Contact IR
+
+`ProfileFilletSideContactChain` is source ordered and contains typed
+`ProfileFilletSideContactEdge` and `ProfileFilletSideContactVertex` elements.
+An edge stores its exact curve/trim, vertices, curve direction, component,
+source-side owner, expected opposite owner, semantic role, provenance, and
+predecessor/successor position. A vertex contact carries no curve, so point
+contacts cannot become degenerate edges.
+
+`ProfileFilletContactEdgeIncidenceContract` allocates one edge identity before
+emission and names both face uses with opposite traversal. The parent side
+and the junction/roll component must reference that same identity. A
+`ProfileFilletSourceSideTrimPlan` groups one or more
+`ProfileFilletSideFaceFragmentPlan` records under the original source-side
+identity, preserving semantic descendants when a side must split.
+
+`ProfileFilletContactVertexIncidence` records edge and face incidence by
+planned vertex identity; no coordinate welding is involved.
+
+## Validation
+
+`ProfileFilletContactGraphValidator` runs before B-rep allocation and reports
+the specific planner invariants:
+
+- `ProfileFilletContactEdgeMissingSecondFace`;
+- `ProfileFilletContactEdgeOverSubscribed`;
+- `ProfileFilletContactOrientationConflict`;
+- `ProfileFilletSideContactChainOpen`;
+- `ProfileFilletSideContactChainOutOfOrder`;
+- `ProfileFilletDuplicateSupportEdge`.
+
+It validates chain order/continuity, a single planned contract per contact
+edge, distinct/opposite face uses, duplicate support identities, explicit
+vertex references, and the absence of zero-length edge contacts.
+
+## Current state
+
+M1 now has a reusable extracted line contact and a preallocated
+side/cylinder incidence contract. Focused tests also model the M2
+roll-plus-support chain and M3 point-not-edge contact. The full parent-shell
+emitter has not yet been rebuilt to consume these contracts, so no whole-loop
+Fillet artifact, volume assertion, inspection JSON, external-kernel result,
+or Preview 1 readiness claim is made by X7 at this point. In particular,
+rounded arc components and SphereSeamCompatibility still need to publish
+their concrete side-chain extraction before the seven-station shell can be
+emitted safely.