Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.