Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add bounded CIR-BREP-T3 stitch executor scaffold and diagnostics
Yuechen Lib3f9b3aab460
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.csnew file mode 100644index 00000000..f7fe755f--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceFamilyStitchExecutorTests.cs@@ -0,0 +1,93 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class SurfaceFamilyStitchExecutorTests+{+ [Fact]+ public void StitchExecutor_BoxCylinder_ConsumesReadyCandidateOrReportsPreciseBlocker()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var cylindrical = EmitCylinder(root);+ var maps = planar.Entries.Where(e => e.Emitted).Select(e => e.IdentityMap ?? EmittedTopologyIdentityMap.Empty)+ .Concat(cylindrical?.IdentityMap is null ? [] : [cylindrical.IdentityMap]);+ var analysis = EmittedTokenPairingAnalyzer.Analyze(maps);+ var plan = SurfaceFamilyStitchCandidatePlanner.Plan(maps, analysis, ShellStitchingDryRunPlanner.Generate(root));++ var result = SurfaceFamilyStitchExecutor.TryExecute(plan, planar, cylindrical);++ Assert.True(result.AppliedCandidateCount > 0 || result.Status is SurfaceFamilyStitchExecutionStatus.Deferred or SurfaceFamilyStitchExecutionStatus.Unsupported);+ if (result.AppliedCandidateCount == 0)+ {+ Assert.True(+ result.Diagnostics.Any(d => d.Contains("shared-edge-merge-unsupported", StringComparison.Ordinal))+ || result.Diagnostics.Any(d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal)));+ }+ }++ [Fact]+ public void StitchExecutor_NoCandidate_NoMutation()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var emptyPlan = new SurfaceFamilyStitchPlanResult(false, [], [], [], ["none"], false);++ var result = SurfaceFamilyStitchExecutor.TryExecute(emptyPlan, planar, null);++ Assert.Null(result.Body);+ Assert.Equal(0, result.AppliedCandidateCount);+ Assert.Contains(result.Diagnostics, d => d.Contains("no-stitch-candidate-no-mutation", StringComparison.Ordinal));+ }++ [Fact]+ public void StitchExecutor_MissingTopologyIds_Defers()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var planar = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);+ var candidate = new SurfaceFamilyStitchCandidate(+ "c1",+ SurfaceFamilyStitchCandidateKind.SharedTrimIdentity,+ SurfaceFamilyStitchCandidateReadiness.Ready,+ new InternalTrimIdentityToken("a", "b", "tok:1", TrimCurveFamily.Circle, "role", "key"),+ new EmittedTopologyIdentityEntry("edge:missingA", EmittedTopologyKind.Edge, null, EmittedTopologyRole.InnerCircularTrim, "orientation-compatible", []),+ new EmittedTopologyIdentityEntry("edge:missingB", EmittedTopologyKind.Edge, null, EmittedTopologyRole.CylindricalTopBoundary, "orientation-compatible", []),+ "orientation-compatible",+ [],+ "o");+ var plan = new SurfaceFamilyStitchPlanResult(true, [candidate], [], [], [], false);++ var result = SurfaceFamilyStitchExecutor.TryExecute(plan, planar, null);++ Assert.Equal(0, result.AppliedCandidateCount);+ Assert.Contains(result.Operations.SelectMany(o => o.Diagnostics), d => d.Contains("missing-local-topology-key", StringComparison.Ordinal));+ }++ [Fact]+ public void StitchExecutor_DoesNotClaimFullShell_OrExportStep()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var result = SurfaceFamilyStitchExecutor.TryExecute(+ SurfaceFamilyStitchCandidatePlanner.PlanBoxCylinder(root),+ new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root),+ EmitCylinder(root));++ Assert.False(result.FullShellClaimed);+ Assert.False(result.StepExportAttempted);+ }++ private static SurfaceMaterializationResult? EmitCylinder(CirNode root)+ {+ var gen = FacePatchCandidateGenerator.Generate(root);+ var candidate = gen.Candidates.SingleOrDefault(c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical+ && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);+ if (candidate is null)+ {+ return null;+ }++ var ready = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 0, 0, 0, 0, 0, 0, 0, [], false);+ return new CylindricalSurfaceMaterializer().EmitRetainedWall(new CylindricalSurfaceMaterializer.RetainedWallEmissionRequest(candidate, ready));+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.csnew file mode 100644index 00000000..2dc62c27--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceFamilyStitchExecutor.cs@@ -0,0 +1,143 @@+using Aetheris.Kernel.Core.Brep;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum SurfaceFamilyStitchExecutionStatus+{+ AssembledPartialBody,+ Deferred,+ Unsupported,+ Failed+}++internal sealed record AppliedStitchOperation(+ string CandidateId,+ string Token,+ string EntryAKey,+ string EntryBKey,+ IReadOnlyList<string> EdgeOrCoedgeIds,+ SurfaceFamilyStitchExecutionStatus Status,+ IReadOnlyList<string> Diagnostics);++internal sealed record SurfaceFamilyStitchExecutionResult(+ bool Success,+ SurfaceFamilyStitchExecutionStatus Status,+ BrepBody? Body,+ int AppliedCandidateCount,+ int DeferredCandidateCount,+ IReadOnlyList<AppliedStitchOperation> Operations,+ IReadOnlyList<string> Diagnostics,+ bool FullShellClaimed,+ bool StepExportAttempted);++internal static class SurfaceFamilyStitchExecutor+{+ internal static SurfaceFamilyStitchExecutionResult TryExecute(+ SurfaceFamilyStitchPlanResult plan,+ PlanarSurfaceMaterializer.PlanarPatchSetMaterializationResult planarPatches,+ SurfaceMaterializationResult? cylindricalPatch)+ {+ var diagnostics = new List<string>+ {+ "stitch-execution-started: bounded stitch executor entered.",+ "step-export-not-attempted: bounded stitch execution does not invoke STEP export.",+ "full-shell-not-claimed: bounded stitch execution does not prove shell closure in CIR-BREP-T3."+ };++ if (plan is null)+ {+ diagnostics.Add("stitch-plan-missing: no stitch plan result was supplied.");+ return Build(false, SurfaceFamilyStitchExecutionStatus.Failed, null, 0, 0, [], diagnostics);+ }++ if (!plan.Candidates.Any())+ {+ diagnostics.Add("no-stitch-candidate-no-mutation: stitch plan contains no candidates.");+ return Build(false, SurfaceFamilyStitchExecutionStatus.Deferred, null, 0, 0, [], diagnostics);+ }++ var operations = new List<AppliedStitchOperation>();+ var ready = plan.Candidates.Where(c => c.Readiness == SurfaceFamilyStitchCandidateReadiness.Ready).ToArray();+ if (ready.Length == 0)+ {+ diagnostics.Add("no-stitch-candidate-no-mutation: stitch plan has candidates, but none are readiness=Ready.");+ return Build(false, SurfaceFamilyStitchExecutionStatus.Deferred, null, 0, plan.Candidates.Count, operations, diagnostics);+ }++ var emitted = planarPatches.Entries.Where(e => e.Emitted).SelectMany(e => e.IdentityMap?.Entries ?? [])+ .Concat(cylindricalPatch?.IdentityMap?.Entries ?? [])+ .ToArray();+ var byKey = emitted.GroupBy(e => e.LocalTopologyKey, StringComparer.Ordinal).ToDictionary(g => g.Key, g => g.First(), StringComparer.Ordinal);++ var unsupported = false;+ var deferredCount = 0;+ var appliedCount = 0;++ foreach (var candidate in ready)+ {+ var opDiagnostics = new List<string>();+ if (candidate.Kind != SurfaceFamilyStitchCandidateKind.SharedTrimIdentity)+ {+ deferredCount++;+ opDiagnostics.Add($"candidate-deferred-unsupported-kind: {candidate.Kind}.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA?.LocalTopologyKey ?? "null", candidate.EntryB?.LocalTopologyKey ?? "null", [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ continue;+ }++ if (candidate.EntryA is null || candidate.EntryB is null)+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-missing-topology-entry: stitch candidate missing EntryA/EntryB.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA?.LocalTopologyKey ?? "null", candidate.EntryB?.LocalTopologyKey ?? "null", [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ continue;+ }++ if (!string.Equals(candidate.OrientationPolicy, "orientation-compatible", StringComparison.Ordinal)+ && !string.Equals(candidate.OrientationPolicy, "orientation-convention-safe", StringComparison.Ordinal))+ {+ deferredCount++;+ opDiagnostics.Add($"candidate-deferred-orientation-policy: {candidate.OrientationPolicy}.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ continue;+ }++ if (plan.AmbiguousItems.Any(a => a.Contains(candidate.Token?.OrderingKey ?? string.Empty, StringComparison.Ordinal))+ || plan.DeferredItems.Any(a => a.Contains(candidate.Token?.OrderingKey ?? string.Empty, StringComparison.Ordinal)))+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-ambiguous-or-missing-mate: associated token has deferred/ambiguous pairing diagnostics.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ continue;+ }++ if (!byKey.ContainsKey(candidate.EntryA.LocalTopologyKey) || !byKey.ContainsKey(candidate.EntryB.LocalTopologyKey))+ {+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-missing-local-topology-key: emitted identity map does not contain one or both candidate local keys.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [], SurfaceFamilyStitchExecutionStatus.Deferred, opDiagnostics));+ continue;+ }++ unsupported = true;+ deferredCount++;+ opDiagnostics.Add("candidate-deferred-topology-contract-blocker: emitted identity entries currently provide edge-local keys only; concrete coedge/loop/face ids are required for safe shared-edge stitch mutation.");+ opDiagnostics.Add("candidate-deferred-topology-remap-blocker: bounded patch bodies are independent Brep bodies and CIR-BREP-T3 has no safe cross-body topology id remap contract.");+ operations.Add(new AppliedStitchOperation(candidate.CandidateId, candidate.Token?.OrderingKey ?? "null", candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey, [candidate.EntryA.LocalTopologyKey, candidate.EntryB.LocalTopologyKey], SurfaceFamilyStitchExecutionStatus.Unsupported, opDiagnostics));+ }++ diagnostics.Add($"ready-candidates-processed: {ready.Length}.");+ diagnostics.Add($"stitch-applied-count: {appliedCount}.");+ diagnostics.Add($"stitch-deferred-count: {deferredCount}.");++ if (unsupported)+ {+ diagnostics.Add("shared-edge-merge-unsupported: blocked by missing concrete coedge/loop/face identity contract and cross-body remap support.");+ return Build(false, SurfaceFamilyStitchExecutionStatus.Unsupported, null, appliedCount, deferredCount, operations, diagnostics);+ }++ return Build(appliedCount > 0, appliedCount > 0 ? SurfaceFamilyStitchExecutionStatus.AssembledPartialBody : SurfaceFamilyStitchExecutionStatus.Deferred, null, appliedCount, deferredCount, operations, diagnostics);+ }++ private static SurfaceFamilyStitchExecutionResult Build(bool success, SurfaceFamilyStitchExecutionStatus status, BrepBody? body, int applied, int deferred, IReadOnlyList<AppliedStitchOperation> operations, IReadOnlyList<string> diagnostics)+ => new(success, status, body, applied, deferred, operations, diagnostics.Distinct().ToArray(), FullShellClaimed: false, StepExportAttempted: false);+}diff --git a/docs/cir-brep-t3-bounded-stitch-execution.md b/docs/cir-brep-t3-bounded-stitch-execution.mdnew file mode 100644index 00000000..31b00258--- /dev/null+++ b/docs/cir-brep-t3-bounded-stitch-execution.md@@ -0,0 +1,48 @@+# CIR-BREP-T3: bounded stitch execution behind stitch-candidate gate++CIR-BREP-T3 introduces a first bounded stitch execution entrypoint for `Subtract(Box,Cylinder)` emitted planar/cylindrical patches.++## Purpose++Attempt deterministic stitch execution only from CIR-BREP-S0 `SurfaceFamilyStitchCandidate` output, while preserving behavior outside this internal bounded path.++## Stitch gate++`SurfaceFamilyStitchExecutor.TryExecute(...)` enforces:++- no candidates => no mutation,+- only `Readiness=Ready` + `Kind=SharedTrimIdentity` considered,+- orientation policy must be compatible/convention-safe,+- deferred/ambiguous token associations are rejected,+- candidate entries must resolve to emitted local topology keys.++## Topology support diagnosis++Current emitted identity contract carries only `LocalTopologyKey` strings with role/orientation + token bridge metadata.+It does not carry concrete coedge/loop/face ids needed to safely mutate shared-edge/coedge relationships across independent emitted patch bodies.++Because each patch emission currently owns its own minimal `BrepBody`, there is no bounded cross-body remap contract in CIR-BREP-T3 for deterministic id merge/pairing.++## Execution strategy chosen++T3 selects **Outcome B (meaningful progression)** strategy:++- execution scaffold is real and invoked over real canonical inputs,+- candidate gating is strict and deterministic,+- executor returns precise unsupported/deferred blockers instead of guessing topology merges,+- no fake shell assembly is produced.++## Behavior guarantees++- `FullShellClaimed` is always `false` in T3.+- `StepExportAttempted` is always `false` in T3.+- Diagnostics explicitly report start, gate decisions, blockers, and non-claims.++## JudgmentEngine decision++JudgmentEngine is not used in T3 because candidate handling is deterministic gated reduction with no admissible competing strategy scoring.+Ambiguous token multiplicity is deferred, not scored.++## Next milestone++Add bounded emitted topology contract extension carrying concrete emitted face/loop/coedge/edge identifiers and a safe cross-body id remap pathway, then attempt one true shared-edge stitch mutation.