Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.10 materialization readiness gate report

Yuechen Li1286b04f53d8
diff --git a/Aetheris.Kernel.Firmament.Tests/MaterializationReadinessAnalyzerTests.cs b/Aetheris.Kernel.Firmament.Tests/MaterializationReadinessAnalyzerTests.cs
new file mode 100644
index 00000000..4836654f
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/MaterializationReadinessAnalyzerTests.cs
@@ -0,0 +1,77 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class MaterializationReadinessAnalyzerTests
+{
+ [Fact]
+ public void Readiness_BoxMinusCylinder_IsEvidenceReadyOrSpecialReady()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+
+ Assert.True(report.SourceSurfaceCount > 0);
+ Assert.True(report.CandidateCount > 0);
+ Assert.True(report.PlannedFaceCount > 0);
+ Assert.True(report.PlannedEdgeUseCount > 0);
+ Assert.Contains(report.OverallReadiness, new[] { EmissionReadiness.EvidenceReadyForEmission, EmissionReadiness.SpecialCaseReady, EmissionReadiness.Deferred });
+ Assert.False(report.TopologyEmissionImplemented);
+ Assert.Contains(report.Diagnostics, d => d.Contains("topology-emission: not implemented", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void Readiness_BoxMinusSphere_NotGenericUnsupported()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3)));
+
+ Assert.Contains(report.Diagnostics, d => d.Contains("planar/spherical => circle exact", StringComparison.Ordinal));
+ Assert.NotEqual(EmissionReadiness.Unsupported, report.OverallReadiness);
+ Assert.DoesNotContain(EmissionBlockingReason.UnsupportedSurfaceFamily, report.BlockingReasons);
+ }
+
+ [Fact]
+ public void Readiness_BoxMinusTorus_BlockedByTrimCapability()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1)));
+
+ Assert.Contains(EmissionBlockingReason.TrimCapability, report.BlockingReasons);
+ Assert.Contains(report.Diagnostics, d => d.Contains("planar/toroidal deferred", StringComparison.Ordinal));
+ Assert.Contains(report.OverallReadiness, new[] { EmissionReadiness.Deferred, EmissionReadiness.Unsupported });
+ }
+
+ [Fact]
+ public void Readiness_NonSubtract_NotApplicable()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2)));
+
+ Assert.Equal(EmissionReadiness.NotApplicable, report.OverallReadiness);
+ Assert.Contains(EmissionBlockingReason.NonSubtractNotApplicable, report.BlockingReasons);
+ }
+
+ [Fact]
+ public void Readiness_CountsAreDeterministic()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3));
+ var first = MaterializationReadinessAnalyzer.Analyze(root);
+ var second = MaterializationReadinessAnalyzer.Analyze(root);
+
+ Assert.Equal(first.SourceSurfaceCount, second.SourceSurfaceCount);
+ Assert.Equal(first.CandidateCount, second.CandidateCount);
+ Assert.Equal(first.PlannedFaceCount, second.PlannedFaceCount);
+ Assert.Equal(first.PlannedLoopCount, second.PlannedLoopCount);
+ Assert.Equal(first.PlannedEdgeUseCount, second.PlannedEdgeUseCount);
+ Assert.Equal(first.CoedgePairingCount, second.CoedgePairingCount);
+ Assert.Equal(first.ClosureEvidenceCount, second.ClosureEvidenceCount);
+ Assert.Equal(first.OverallReadiness, second.OverallReadiness);
+ Assert.Equal(first.BlockingReasons, second.BlockingReasons);
+ }
+
+ [Fact]
+ public void Readiness_DoesNotEmitBRepTopology()
+ {
+ var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8)));
+
+ Assert.False(report.TopologyEmissionImplemented);
+ Assert.Contains(report.LayerSummaries, l => l.LayerName == "pairing-evidence");
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
new file mode 100644
index 00000000..81ff8162
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs
@@ -0,0 +1,209 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum EmissionReadiness
+{
+ NotApplicable,
+ EvidenceReadyForEmission,
+ SpecialCaseReady,
+ Deferred,
+ Unsupported
+}
+
+internal enum EmissionBlockingReason
+{
+ None,
+ SourceSurfaceExtraction,
+ TrimCapability,
+ RetentionClassification,
+ LoopScaffolding,
+ LoopGrouping,
+ TopologyPlanning,
+ LoopClosure,
+ CoedgePairing,
+ Adjacency,
+ UnsupportedSurfaceFamily,
+ NonSubtractNotApplicable,
+ TopologyEmissionNotImplemented
+}
+
+internal sealed record ReadinessLayerSummary(
+ string LayerName,
+ EmissionReadiness Readiness,
+ IReadOnlyList<EmissionBlockingReason> BlockingReasons,
+ IReadOnlyList<string> Diagnostics,
+ IReadOnlyDictionary<string, int> Counts);
+
+internal sealed record MaterializationReadinessReport(
+ bool Success,
+ EmissionReadiness OverallReadiness,
+ IReadOnlyList<EmissionBlockingReason> BlockingReasons,
+ IReadOnlyList<ReadinessLayerSummary> LayerSummaries,
+ int SourceSurfaceCount,
+ int CandidateCount,
+ int PlannedFaceCount,
+ int PlannedLoopCount,
+ int PlannedEdgeUseCount,
+ int CoedgePairingCount,
+ int ClosureEvidenceCount,
+ IReadOnlyList<string> Diagnostics,
+ bool TopologyEmissionImplemented);
+
+internal static class MaterializationReadinessAnalyzer
+{
+ internal static MaterializationReadinessReport Analyze(CirNode root, NativeGeometryReplayLog? replayLog = null)
+ {
+ var source = SourceSurfaceExtractor.Extract(root, replayLog);
+ var nonSubtract = root is not CirSubtractNode;
+
+ var candidates = FacePatchCandidateGenerator.Generate(root, replayLog);
+ var topology = TopologyAssemblyDryRunPlanner.Generate(candidates);
+ var pairing = TopologyPairingEvidenceGenerator.Generate(topology);
+
+ var layers = new List<ReadinessLayerSummary>
+ {
+ SummarizeSource(source),
+ SummarizeCandidates(candidates),
+ SummarizeTopology(topology),
+ SummarizePairing(pairing)
+ };
+
+ var overall = nonSubtract ? EmissionReadiness.NotApplicable : Reduce(layers.Select(l => l.Readiness));
+ var blocking = layers.SelectMany(l => l.BlockingReasons)
+ .Where(r => r != EmissionBlockingReason.None)
+ .Distinct()
+ .OrderBy(r => r)
+ .ToList();
+ if (nonSubtract && !blocking.Contains(EmissionBlockingReason.NonSubtractNotApplicable))
+ {
+ blocking.Add(EmissionBlockingReason.NonSubtractNotApplicable);
+ }
+ var blockingReasons = blocking.Distinct().OrderBy(r => r).ToArray();
+
+ var diagnostics = new List<string>
+ {
+ $"source-surface: extracted {source.Descriptors.Count} surfaces",
+ $"face-patch: generated {candidates.Candidates.Count} candidates",
+ $"topology-dry-run: planned {topology.PlannedFaces.Count} faces and {topology.PlannedFaces.SelectMany(f => f.LoopGroups).Count()} loops",
+ $"pairing-evidence: edge-uses={pairing.PlannedEdgeUses.Count} coedge-pairings={pairing.PlannedCoedgePairings.Count} closure={pairing.LoopClosureEvidence.Count}",
+ "topology-emission: not implemented",
+ "judgment-engine-not-used: readiness gate is a conservative deterministic reduction with no competing bounded strategies."
+ };
+ diagnostics.AddRange(candidates.TrimCapabilitySummaries
+ .Where(t => (t.FamilyA == SurfacePatchFamily.Planar && t.FamilyB == SurfacePatchFamily.Spherical) || (t.FamilyA == SurfacePatchFamily.Spherical && t.FamilyB == SurfacePatchFamily.Planar))
+ .Select(_ => "trim-capability: planar/spherical => circle exact"));
+ diagnostics.AddRange(pairing.LoopClosureEvidence.Where(c => c.ClosureStatus == LoopClosureStatus.ClosedByDescriptor)
+ .Select(_ => "loop-closure: closed by exact circle descriptor"));
+ diagnostics.AddRange(pairing.PlannedCoedgePairings.Where(p => p.PairingKind == PlannedCoedgePairingKind.SharedTrimIdentity)
+ .Select(_ => "coedge-pairing: promoted by internal trim identity token"));
+ diagnostics.AddRange(pairing.PlannedCoedgePairings.Where(p => p.Readiness == TopologyPairingReadiness.Deferred)
+ .Select(_ => "coedge-pairing: deferred; missing one-to-one identity"));
+ diagnostics.AddRange(candidates.TrimCapabilitySummaries
+ .Where(t => (t.FamilyA == SurfacePatchFamily.Planar && t.FamilyB == SurfacePatchFamily.Toroidal) || (t.FamilyA == SurfacePatchFamily.Toroidal && t.FamilyB == SurfacePatchFamily.Planar))
+ .Select(t => $"trim-capability: planar/toroidal deferred; {t.Reason}"));
+
+ return new MaterializationReadinessReport(
+ Success: source.IsSuccess && candidates.Candidates.Count > 0,
+ OverallReadiness: overall,
+ BlockingReasons: blockingReasons,
+ LayerSummaries: layers,
+ SourceSurfaceCount: source.Descriptors.Count,
+ CandidateCount: candidates.Candidates.Count,
+ PlannedFaceCount: topology.PlannedFaces.Count,
+ PlannedLoopCount: topology.PlannedFaces.SelectMany(f => f.LoopGroups).Count(),
+ PlannedEdgeUseCount: pairing.PlannedEdgeUses.Count,
+ CoedgePairingCount: pairing.PlannedCoedgePairings.Count,
+ ClosureEvidenceCount: pairing.LoopClosureEvidence.Count,
+ Diagnostics: diagnostics.Distinct().ToArray(),
+ TopologyEmissionImplemented: false);
+ }
+
+ private static ReadinessLayerSummary SummarizeSource(SourceSurfaceExtractionResult source)
+ {
+ var readiness = source.IsSuccess ? EmissionReadiness.EvidenceReadyForEmission : EmissionReadiness.Unsupported;
+ var reason = source.IsSuccess ? EmissionBlockingReason.None : EmissionBlockingReason.SourceSurfaceExtraction;
+ return new("source-surface-extraction", readiness, [reason], source.Diagnostics.Select(d => $"{d.Code}: {d.Message}").Concat(source.UnsupportedNodeReasons).ToArray(),
+ new Dictionary<string, int> { ["source-surfaces"] = source.Descriptors.Count, ["unsupported-nodes"] = source.UnsupportedNodeReasons.Count });
+ }
+
+ private static ReadinessLayerSummary SummarizeCandidates(FacePatchCandidateGenerationResult candidates)
+ {
+ var readiness = MapCandidate(candidates);
+ var reasons = new List<EmissionBlockingReason>();
+ if (readiness == EmissionReadiness.Deferred) reasons.Add(EmissionBlockingReason.TrimCapability);
+ if (readiness == EmissionReadiness.Unsupported) reasons.Add(EmissionBlockingReason.UnsupportedSurfaceFamily);
+ if (candidates.Candidates.All(c => c.RetentionRole == FacePatchRetentionRole.NotApplicable)) reasons.Add(EmissionBlockingReason.NonSubtractNotApplicable);
+ return new("face-patch-candidates", readiness, reasons, candidates.Diagnostics, new Dictionary<string, int>
+ {
+ ["candidates"] = candidates.Candidates.Count,
+ ["retained-loops"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(),
+ ["loop-groups"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoopGroups).Count(),
+ ["deferred-reasons"] = candidates.DeferredReasons.Count
+ });
+ }
+
+ private static EmissionReadiness MapCandidate(FacePatchCandidateGenerationResult candidates)
+ {
+ if (candidates.Candidates.All(c => c.RetentionRole == FacePatchRetentionRole.NotApplicable)) return EmissionReadiness.NotApplicable;
+ if (candidates.Candidates.Any(c => c.Readiness == FacePatchCandidateReadiness.Unsupported)) return EmissionReadiness.Unsupported;
+ if (candidates.Candidates.Any(c => c.Readiness is FacePatchCandidateReadiness.TrimDeferred or FacePatchCandidateReadiness.RetentionDeferred)) return EmissionReadiness.Deferred;
+ return candidates.Candidates.Any(c => c.TrimCapability?.Classification == TrimCapabilityClassification.SpecialCaseOnly)
+ ? EmissionReadiness.SpecialCaseReady
+ : EmissionReadiness.EvidenceReadyForEmission;
+ }
+
+ private static ReadinessLayerSummary SummarizeTopology(TopologyAssemblyDryRunResult topology)
+ {
+ var readiness = topology.Readiness switch
+ {
+ TopologyAssemblyReadiness.ExactPlanReady => EmissionReadiness.EvidenceReadyForEmission,
+ TopologyAssemblyReadiness.SpecialCasePlanReady => EmissionReadiness.SpecialCaseReady,
+ TopologyAssemblyReadiness.Deferred => EmissionReadiness.Deferred,
+ TopologyAssemblyReadiness.Unsupported => EmissionReadiness.Unsupported,
+ _ => EmissionReadiness.NotApplicable
+ };
+ var reasons = new List<EmissionBlockingReason>();
+ if (readiness == EmissionReadiness.Deferred) reasons.Add(EmissionBlockingReason.TopologyPlanning);
+ if (readiness == EmissionReadiness.Unsupported) reasons.Add(EmissionBlockingReason.TopologyPlanning);
+ return new("topology-dry-run", readiness, reasons, topology.Diagnostics, new Dictionary<string, int>
+ {
+ ["planned-faces"] = topology.PlannedFaces.Count,
+ ["planned-loops"] = topology.PlannedFaces.SelectMany(f => f.LoopGroups).Count(),
+ ["adjacency-hints"] = topology.PlannedAdjacencies.Count
+ });
+ }
+
+ private static ReadinessLayerSummary SummarizePairing(TopologyPairingEvidenceResult pairing)
+ {
+ var readiness = pairing.Readiness switch
+ {
+ TopologyPairingReadiness.ExactReady => EmissionReadiness.EvidenceReadyForEmission,
+ TopologyPairingReadiness.SpecialCaseReady => EmissionReadiness.SpecialCaseReady,
+ TopologyPairingReadiness.Deferred => EmissionReadiness.Deferred,
+ TopologyPairingReadiness.Unsupported => EmissionReadiness.Unsupported,
+ _ => EmissionReadiness.NotApplicable
+ };
+ var reasons = new List<EmissionBlockingReason>();
+ if (pairing.PlannedCoedgePairings.Any(p => p.Readiness == TopologyPairingReadiness.Deferred)) reasons.Add(EmissionBlockingReason.CoedgePairing);
+ if (pairing.LoopClosureEvidence.Any(c => c.Readiness == TopologyPairingReadiness.Deferred)) reasons.Add(EmissionBlockingReason.LoopClosure);
+ if (pairing.LoopClosureEvidence.Any(c => c.Readiness == TopologyPairingReadiness.Unsupported)) reasons.Add(EmissionBlockingReason.LoopClosure);
+ return new("pairing-evidence", readiness, reasons.Distinct().ToArray(), pairing.Diagnostics, new Dictionary<string, int>
+ {
+ ["planned-edge-uses"] = pairing.PlannedEdgeUses.Count,
+ ["planned-coedge-pairings"] = pairing.PlannedCoedgePairings.Count,
+ ["loop-closure-evidence"] = pairing.LoopClosureEvidence.Count
+ });
+ }
+
+ private static EmissionReadiness Reduce(IEnumerable<EmissionReadiness> values)
+ {
+ var arr = values.ToArray();
+ if (arr.Length == 0) return EmissionReadiness.NotApplicable;
+ if (arr.Any(v => v == EmissionReadiness.Unsupported)) return EmissionReadiness.Unsupported;
+ if (arr.Any(v => v == EmissionReadiness.Deferred)) return EmissionReadiness.Deferred;
+ if (arr.Any(v => v == EmissionReadiness.SpecialCaseReady)) return EmissionReadiness.SpecialCaseReady;
+ if (arr.Any(v => v == EmissionReadiness.EvidenceReadyForEmission)) return EmissionReadiness.EvidenceReadyForEmission;
+ return EmissionReadiness.NotApplicable;
+ }
+}
diff --git a/docs/cir-f810-materialization-readiness-gate.md b/docs/cir-f810-materialization-readiness-gate.md
new file mode 100644
index 00000000..f7713a6b
--- /dev/null
+++ b/docs/cir-f810-materialization-readiness-gate.md
@@ -0,0 +1,69 @@
+# CIR-F8.10: topology readiness summary + first emission gate
+
+CIR-F8.10 adds `MaterializationReadinessAnalyzer` as a dry-run-only aggregation gate over existing F8 evidence layers.
+
+## Purpose
+
+Provide a deterministic readiness report answering whether a CIR subtree has enough dry-run evidence for future BRep emission attempts, while explicitly keeping topology emission unimplemented.
+
+## Evidence readiness vs emission implementation
+
+- `EmissionReadiness` reports **evidence readiness only**.
+- `TopologyEmissionImplemented` remains `false` in all outcomes for F8.10.
+- No BRep face/loop/edge/coedge/vertex/shell entities are created.
+
+## Readiness values
+
+- `EvidenceReadyForEmission`
+- `SpecialCaseReady`
+- `Deferred`
+- `Unsupported`
+- `NotApplicable`
+
+Conservative precedence: `Unsupported > Deferred > SpecialCaseReady > EvidenceReadyForEmission > NotApplicable`.
+
+## Blocking reasons
+
+- `SourceSurfaceExtraction`
+- `TrimCapability`
+- `RetentionClassification`
+- `LoopScaffolding`
+- `LoopGrouping`
+- `TopologyPlanning`
+- `LoopClosure`
+- `CoedgePairing`
+- `Adjacency`
+- `UnsupportedSurfaceFamily`
+- `NonSubtractNotApplicable`
+- `TopologyEmissionNotImplemented`
+
+## Layer summaries
+
+The report summarizes:
+
+1. source-surface extraction
+2. face patch candidate/retention/loop scaffold evidence
+3. topology dry-run planning
+4. edge/coedge pairing and loop-closure evidence
+
+Each layer carries readiness, blocking reasons, diagnostics, and deterministic counts.
+
+## Example outcomes
+
+- `Subtract(Box, Cylinder)`: typically `EvidenceReadyForEmission` or `SpecialCaseReady`; may still be `Deferred` if pairing/closure evidence is deferred.
+- `Subtract(Box, Sphere)`: not generic unsupported; reports planar/spherical circle-exact diagnostics and any true deferred blocker.
+- `Subtract(Box, Torus)`: blocked at trim capability with planar/toroidal quartic/algebraic deferred diagnostics.
+- non-subtract roots: `NotApplicable` for this subtract-focused gate.
+
+## JudgmentEngine usage decision
+
+`JudgmentEngine` is not used in F8.10. The gate logic is a monotonic conservative reduction over existing layer statuses without competing bounded strategies.
+
+## Deferred in F8.10
+
+- Actual topology emission remains unimplemented.
+- Exact parameter solving and full coedge/adjacency closure materialization remain future work.
+
+## Recommended next step
+
+Use this report as the first preflight contract before adding family-specific BRep emission stages, failing early on explicit layer blockers rather than attempting unsafe partial emission.