fix: skip material-merge clash check for single-child stacks (#5576)

The early material-clash pre-check in ContainerBlueprintNode::connectImpl iterated over ShellStack::mergedFaces() for every shell regardless of how many children were present. For an AxisZ stack that returns {OuterCylinder, InnerCylinder}, which are only actually merged when two or more children are stacked. With a single child no portal merge takes place, so flagging material on those faces was a false positive that caused a spurious warning (or, in strict mode, a throw).

Fix: guard the merged-face loop with shells.size() > 1 so the check is skipped entirely when there is nothing to merge.

Author: paulgessinger

Core/src/Geometry/ContainerBlueprintNode.cpp

@@ -251,14 +251,19 @@ PortalShellBase& ContainerBlueprintNode::connectImpl(
   // survive the merge and would otherwise trigger a deep, hard-to-trace failure
   // inside the stack shell construction. Faces that are *fused* (e.g. the
   // boundary between two stacked volumes) legitimately carry material and are
-  // not flagged here.
+  // not flagged here.  With only a single child there is no actual merge, so
+  // the check is skipped entirely to avoid false positives.
   const PortalMaterialMergePolicy materialPolicy =
       options.keepGoingOnMaterialMergeFailure
           ? PortalMaterialMergePolicy::eDiscardAndMark
           : PortalMaterialMergePolicy::eThrow;
 
+  // With a single child there is nothing to merge, so the "merged" faces are
+  // actually kept as-is. Skip the clash check to avoid false positives.
   std::vector<std::string> materialClashes;
-  for (auto face : ShellStack::mergedFaces(direction())) {
+  for (auto face : shells.size() > 1
+                       ? ShellStack::mergedFaces(direction())
+                       : std::vector<typename ShellStack::Face>{}) {
     for (auto* shell : shells) {
       auto portal = shell->portal(face);
       if (portal != nullptr && portal->surface().hasMaterial()) {

Tests/UnitTests/Core/Geometry/BlueprintApiTests.cpp

@@ -564,4 +564,53 @@ BOOST_AUTO_TEST_CASE(MaterialOnMergedPortalKeepGoing) {
   BOOST_CHECK_GE(markerCount, 1u);
 }
 
+BOOST_AUTO_TEST_CASE(MaterialOnMergedPortalKeepGoingSingleChildFalseWarning) {
+  // Reproducer for a false-positive in the early material-clash check:
+  // a single-child AxisZ stack must NOT trigger a merge-material error because
+  // no portal merge actually happens.  With keepGoingOnMaterialMergeFailure at
+  // its default (false / strict), construction must succeed without throwing.
+  Transform3 base{Transform3::Identity()};
+
+  Blueprint::Config cfg;
+  cfg.envelope[AxisDirection::AxisZ] = {20_mm, 20_mm};
+  cfg.envelope[AxisDirection::AxisR] = {0_mm, 20_mm};
+  auto root = std::make_unique<Blueprint>(cfg);
+
+  root->addCylinderContainer("Stack", AxisDirection::AxisZ, [&](auto& stack) {
+    using enum AxisDirection;
+    using enum AxisBoundaryType;
+    using enum CylinderVolumeBounds::Face;
+
+    stack.addMaterial("Material", [&](auto& mat) {
+      mat.configureFace(OuterCylinder, {AxisRPhi, Bound, 20},
+                        {AxisZ, Bound, 20});
+      mat.addStaticVolume(
+          base, std::make_shared<CylinderVolumeBounds>(0_mm, 100_mm, 100_mm),
+          "VolumeA");
+    });
+  });
+
+  // Use strict mode (keepGoingOnMaterialMergeFailure = false by default).
+  // The single-child stack must not be mistaken for a real merge, so no
+  // exception should be thrown.
+  Experimental::BlueprintOptions options;
+
+  std::unique_ptr<const TrackingGeometry> trackingGeometry;
+  BOOST_REQUIRE_NO_THROW(trackingGeometry =
+                             root->construct(options, gctx, *logger));
+  BOOST_REQUIRE(trackingGeometry != nullptr);
+
+  std::size_t markerCount = 0;
+  trackingGeometry->visitSurfaces(
+      [&](const Surface* surface) {
+        if (surface != nullptr && surface->surfaceMaterial() != nullptr &&
+            dynamic_cast<const MergedMaterialMarker*>(
+                surface->surfaceMaterial()) != nullptr) {
+          ++markerCount;
+        }
+      },
+      false);
+  BOOST_CHECK_EQUAL(markerCount, 0u);
+}
+
 BOOST_AUTO_TEST_SUITE_END();