wip(assembler): M2 round 4 -- WorldAssemblerHybridV2: exact contacts, tagged tiles 1.18-1.27x MC

The round-3 'field contact error' measured hit-to-anchor distance; V2 contacts are 0 cm and on the zero
isosurface. Tagged-tile cost 5.7-6.7x -> 1.175-1.270x MC; organic 0.998x. Bound, shelf-thickness and route
audits rerun with negative controls; W1/W8/W16 stable; V1 and MarchingCubesV1 unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MmSoF64BbRFmk9C3p1VsBJ

Source/VoxelForge/Private/VoxelHybridSharpMesher.h

@@ -43,6 +43,11 @@ namespace VoxelHybridSharpMesher
         else V.Z = Value;
     }
 
+    inline int32 IntAxisValue(const FIntVector& V, int32 Axis)
+    {
+        return Axis == 0 ? V.X : (Axis == 1 ? V.Y : V.Z);
+    }
+
     struct FPlane
     {
         uint64 Id = 0;
@@ -229,6 +234,109 @@ namespace VoxelHybridSharpMesher
         return SDF;
     }
 
+    struct FPreparedFeatureBox
+    {
+        uint64 StableId = 0;
+        double Minimum[3]{};
+        double Maximum[3]{};
+    };
+
+    inline std::vector<FPreparedFeatureBox> PrepareFeatureBoxes(
+        const TArray<FVoxelHybridSharpFeatureBox>& Features)
+    {
+        std::vector<FPreparedFeatureBox> Prepared;
+        Prepared.reserve(static_cast<std::size_t>(Features.Num()));
+        for (const FVoxelHybridSharpFeatureBox& Feature : Features)
+        {
+            FPreparedFeatureBox Box;
+            Box.StableId = Feature.StableId;
+            for (int32 Axis = 0; Axis < 3; ++Axis)
+            {
+                Box.Minimum[Axis] = static_cast<double>(Feature.MinimumSubvoxels[Axis])
+                    / SubvoxelsPerVoxel;
+                Box.Maximum[Axis] = static_cast<double>(Feature.MaximumSubvoxels[Axis])
+                    / SubvoxelsPerVoxel;
+            }
+            Prepared.push_back(Box);
+        }
+        return Prepared;
+    }
+
+    // MC interpolates the sampled field. A finite hard box is only included by the field at
+    // samples inside it, so an edge can interpolate away from the box plane when the box face
+    // lies between lattice points. For V2, keep the MC connectivity and move only roots whose
+    // lattice edge crosses a tagged analytic face. This is deterministic and leaves tile edges
+    // to the unchanged MC/skirt path.
+    inline bool TrySnapFeatureEdge(const std::vector<FPreparedFeatureBox>& Features,
+        const FIntVector& OriginVoxels, const FIntVector& LocalStart, int32 Axis,
+        const FVector& ChunkWorldPos, float GeometryVoxelSize,
+        FVector& InOutWorldPosition, FVector& OutNormal, uint64& OutSplitKey)
+    {
+        const double EdgeStart = static_cast<double>(IntAxisValue(OriginVoxels, Axis)
+            + IntAxisValue(LocalStart, Axis));
+        const double EdgeEnd = EdgeStart + 1.0;
+        const double EdgeLow = FMath::Min(EdgeStart, EdgeEnd);
+        const double EdgeHigh = FMath::Max(EdgeStart, EdgeEnd);
+        const double RootVoxel = static_cast<double>(IntAxisValue(OriginVoxels, Axis))
+            + (AxisValue(InOutWorldPosition, Axis) - AxisValue(ChunkWorldPos, Axis))
+                / GeometryVoxelSize;
+        constexpr double Tolerance = 1.0e-9;
+        double BestDistance = std::numeric_limits<double>::infinity();
+        uint64 BestStableId = std::numeric_limits<uint64>::max();
+        uint64 BestFaceId = 0;
+        double BestPlane = 0.0;
+        int32 BestSide = 0;
+
+        for (const FPreparedFeatureBox& Feature : Features)
+        {
+            bool bWithinFaceSpan = true;
+            for (int32 OtherAxis = 0; OtherAxis < 3; ++OtherAxis)
+            {
+                if (OtherAxis == Axis) continue;
+                const double Coordinate = static_cast<double>(IntAxisValue(OriginVoxels, OtherAxis)
+                    + IntAxisValue(LocalStart, OtherAxis));
+                if (Coordinate < Feature.Minimum[OtherAxis] - Tolerance
+                    || Coordinate > Feature.Maximum[OtherAxis] + Tolerance)
+                {
+                    bWithinFaceSpan = false;
+                    break;
+                }
+            }
+            if (!bWithinFaceSpan) continue;
+
+            for (int32 Side = 0; Side < 2; ++Side)
+            {
+                const double Plane = Side == 0
+                    ? Feature.Minimum[Axis] : Feature.Maximum[Axis];
+                if (Plane < EdgeLow - Tolerance || Plane > EdgeHigh + Tolerance) continue;
+                const double Distance = FMath::Abs(Plane - RootVoxel);
+                const uint64 FaceId = Feature.StableId ^ (0x9e3779b97f4a7c15ull
+                    + static_cast<uint64>(Axis * 2 + Side + 1));
+                if (Distance > BestDistance + Tolerance
+                    || (FMath::Abs(Distance - BestDistance) <= Tolerance
+                        && std::tie(Feature.StableId, FaceId)
+                            >= std::tie(BestStableId, BestFaceId)))
+                {
+                    continue;
+                }
+                BestDistance = Distance;
+                BestStableId = Feature.StableId;
+                BestFaceId = FaceId != 0 ? FaceId : static_cast<uint64>(Axis + 1);
+                BestPlane = Plane;
+                BestSide = Side;
+            }
+        }
+
+        if (BestFaceId == 0) return false;
+        SetAxisValue(InOutWorldPosition, Axis, AxisValue(ChunkWorldPos, Axis)
+            + (BestPlane - static_cast<double>(IntAxisValue(OriginVoxels, Axis)))
+                * GeometryVoxelSize);
+        OutNormal = FVector::ZeroVector;
+        SetAxisValue(OutNormal, Axis, BestSide == 0 ? -1.0 : 1.0);
+        OutSplitKey = BestFaceId;
+        return true;
+    }
+
     inline uint64 SelectFeature(const FRoot& Root, int32 Axis)
     {
         if (Root.Planes.empty()) return 0;