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