feat(decals): tiles de decal de sòl compten com a pintats des del load

source/game/map/paint_layer.cpp

@@ -12,6 +12,27 @@
 #include "game/map/map.hpp"
 #include "game/map/tilemap.hpp"
 
+// CONTRACTE BUS DE PINTAT
+// -----------------------
+// `on_tile_entered` — senyal FÍSICA: un jugador acaba d'entrar a un tile.
+//   La publica `Player::publishTileEnteredIfChanged`. La consumeix aquest
+//   `PaintLayer` per decidir si renderitzar el tile com a pintat (filtra
+//   per `Map::isPaintable` i aplica la regla "primer que pinta guanya").
+//
+// `tile_painted` — senyal LÒGICA: un tile compta com a pintat per a la
+//   lògica de joc (sarcòfags i, en el futur, HUD %completat, events
+//   derivats). La publica el `PaintLayer` quan confirma un pintat físic,
+//   i també la publica `EntityManager::loadFromLevel` com a broadcast
+//   inicial per als tiles ocupats per decals de sòl (Hole, etc.) — que
+//   el jugador mai podrà trepitjar perquè cauria al forat i els
+//   sarcòfags vecins necessiten que aquests tiles comptin com a pintats
+//   per completar el perímetre.
+//
+// REGLA: NO connectar `PaintLayer` al canal `tile_painted` per
+// renderitzar. Si ho féssim, els broadcasts inicials de decals pintarien
+// visualment els tiles d'agujero, incoherent amb la representació
+// gràfica del decal.
+
 namespace {
 
     // Blit d'un tile del tileset sobre un buffer ARGB de destí, respectant