wip(assembler): round L7 -- shared column cache across workers: whole view 16-19% faster, world unchanged

SharedColumnCache.h: a world-owned, bounded 4-way second-tier cache of exact column values
(heightfield and floating islands), keyed by recipe/plan identity plus content hash, XY and island
id. Lock-free seqlock reads; set-local spin lock on misses. The FLazy thread-local tier stays
first. 83.6% of repeated column work was cross-worker; formula evaluations -60.9%.
W12 L1 view: Luna 2.165 -> 1.754 s; reviewer interleaved 2.059 -> 1.722 s. 8 m crossing new tiles
82 -> 52 ms. +66 MiB peak RSS. All hashes (whole view, per-LOD, exact queries, islands seed 0)
identical at W1/W8/W12, Clang off and GCC default. MSVC/UBT not compiled here.

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

Standalone/Core/src/CoreNamespacePreamble.h

@@ -55,6 +55,7 @@
 #include "Json.h"
 #include "VoxelForgeCore/VoxelForgeCore.h"
 #include "VoxelForgeCore/ThreadLocalStorage.h"
+#include "VoxelForgeCore/SharedColumnCache.h"
 
 // Keep Core's expression-level FMA behavior fixed regardless of the toolchain setting.
 // Clang's "fast" mode ignores the pragma, so Core's runtime self-test rejects that build.

Standalone/Core/src/FloatingIslandsInternal.h

@@ -425,6 +425,9 @@ namespace floating_island_detail
     struct FIslandColumnCacheEntry
     {
         bool bValid=false;
+        const FloatingIslandRecipeV1* RecipeIdentity=nullptr;
+        const FloatingIslandPlanV1* PlanIdentity=nullptr;
+        std::uint64_t RecipeContentHash=0,PlanContentHash=0;
         std::uint32_t Seed=0;
         std::uint64_t StableId=0;
         std::int64_t SampleX=0,SampleY=0,CenterX=0,CenterY=0,TopZ=0,Radius=0,TopHalf=0;
@@ -432,9 +435,12 @@ namespace floating_island_detail
         double DeltaX=0.0,DeltaY=0.0,Radial=0.0,Angle=0.0,LobePhase=0.0,TopSurface=0.0;
     };
 
+    using FSharedIslandColumnCache =
+        VoxelForgeCoreShared::TSharedColumnValueCache<FIslandColumnCacheEntry,16384,4>;
+
     inline const FIslandColumnCacheEntry& IslandColumnCache(
-        const FloatingIslandRecipeV1& recipe,const FloatingIslandAnchorV1& island,
-        double x,double y)
+        const FloatingIslandRecipeV1& recipe,const FloatingIslandPlanV1& plan,
+        const FloatingIslandAnchorV1& island,double x,double y)
     {
         // Density samples arrive on integer Core lattice columns; reuse the exact column metrics
         // across Z samples without changing the field value or touching shared world state.
@@ -450,7 +456,10 @@ namespace floating_island_detail
         std::uint64_t IndexKey=island.stableId
             ^(static_cast<std::uint64_t>(SampleX)*0x9e3779b97f4a7c15ull)
             ^(static_cast<std::uint64_t>(SampleY)*0xc2b2ae3d27d4eb4full)
-            ^(static_cast<std::uint64_t>(recipe.seed)<<23);
+            ^(static_cast<std::uint64_t>(recipe.seed)<<23)
+            ^recipe.contentHash^std::rotl(plan.contentHash,17)
+            ^static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&recipe))
+            ^std::rotl(static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&plan)),31);
         IndexKey^=IndexKey>>33;
         IndexKey*=0xff51afd7ed558ccdull;
         IndexKey^=IndexKey>>33;
@@ -459,7 +468,9 @@ namespace floating_island_detail
         for(std::size_t Way=0;Way<Ways;++Way)
         {
             FIslandColumnCacheEntry& Entry=cache[Base+Way];
-            const bool bKeyMatches=Entry.bValid&&Entry.Seed==recipe.seed
+            const bool bKeyMatches=Entry.bValid&&Entry.RecipeIdentity==&recipe
+                &&Entry.PlanIdentity==&plan&&Entry.RecipeContentHash==recipe.contentHash
+                &&Entry.PlanContentHash==plan.contentHash&&Entry.Seed==recipe.seed
                 &&Entry.StableId==island.stableId
                 &&Entry.SampleX==SampleX&&Entry.SampleY==SampleY
                 &&Entry.CenterX==island.centerSubvoxels[0]
@@ -473,32 +484,53 @@ namespace floating_island_detail
             if(!Entry.bValid)Replacement=&Entry;
         }
 
-        FIslandColumnCacheEntry& Entry=*Replacement;
-        Entry.bValid=true;
-        Entry.Seed=recipe.seed;
-        Entry.StableId=island.stableId;
-        Entry.SampleX=SampleX;
-        Entry.SampleY=SampleY;
-        Entry.CenterX=island.centerSubvoxels[0];
-        Entry.CenterY=island.centerSubvoxels[1];
-        Entry.TopZ=island.topZSubvoxels;
-        Entry.Radius=island.radiusSubvoxels;
-        Entry.TopHalf=island.topHalfSubvoxels;
-        Entry.TopFlattenQ16=recipe.topFlattenQ16;
-        Entry.ContourWarp=recipe.contourWarpSubvoxels;
-        Entry.DeltaX=x-static_cast<double>(island.centerSubvoxels[0]);
-        Entry.DeltaY=y-static_cast<double>(island.centerSubvoxels[1]);
-        Entry.Radial=std::hypot(Entry.DeltaX,Entry.DeltaY);
-        Entry.Angle=std::atan2(Entry.DeltaY,Entry.DeltaX);
-        Entry.LobePhase=LobePhase(recipe,island);
-        const double EffectiveRadius=std::max(1.0,static_cast<double>(island.radiusSubvoxels)
-            +LobeOffsetWithPhase(recipe,Entry.Angle,static_cast<double>(island.topZSubvoxels),
-                Entry.LobePhase));
-        const double Edge=std::clamp(Entry.Radial/EffectiveRadius,0.0,1.0);
-        const double Drop=(1.0-Q16ToDouble(recipe.topFlattenQ16))
-            *static_cast<double>(island.topHalfSubvoxels)*2.0*Edge*Edge;
-        Entry.TopSurface=static_cast<double>(island.topZSubvoxels)-Drop;
-        return Entry;
+        const auto build=[&]()
+        {
+            FIslandColumnCacheEntry Entry;
+            Entry.bValid=true;
+            Entry.RecipeIdentity=&recipe;
+            Entry.PlanIdentity=&plan;
+            Entry.RecipeContentHash=recipe.contentHash;
+            Entry.PlanContentHash=plan.contentHash;
+            Entry.Seed=recipe.seed;
+            Entry.StableId=island.stableId;
+            Entry.SampleX=SampleX;
+            Entry.SampleY=SampleY;
+            Entry.CenterX=island.centerSubvoxels[0];
+            Entry.CenterY=island.centerSubvoxels[1];
+            Entry.TopZ=island.topZSubvoxels;
+            Entry.Radius=island.radiusSubvoxels;
+            Entry.TopHalf=island.topHalfSubvoxels;
+            Entry.TopFlattenQ16=recipe.topFlattenQ16;
+            Entry.ContourWarp=recipe.contourWarpSubvoxels;
+            Entry.DeltaX=x-static_cast<double>(island.centerSubvoxels[0]);
+            Entry.DeltaY=y-static_cast<double>(island.centerSubvoxels[1]);
+            Entry.Radial=std::hypot(Entry.DeltaX,Entry.DeltaY);
+            Entry.Angle=std::atan2(Entry.DeltaY,Entry.DeltaX);
+            Entry.LobePhase=LobePhase(recipe,island);
+            const double EffectiveRadius=std::max(1.0,static_cast<double>(island.radiusSubvoxels)
+                +LobeOffsetWithPhase(recipe,Entry.Angle,static_cast<double>(island.topZSubvoxels),
+                    Entry.LobePhase));
+            const double Edge=std::clamp(Entry.Radial/EffectiveRadius,0.0,1.0);
+            const double Drop=(1.0-Q16ToDouble(recipe.topFlattenQ16))
+                *static_cast<double>(island.topHalfSubvoxels)*2.0*Edge*Edge;
+            Entry.TopSurface=static_cast<double>(island.topZSubvoxels)-Drop;
+            return Entry;
+        };
+        FIslandColumnCacheEntry Entry{};
+        if(auto* shared=FSharedIslandColumnCache::threadActive())
+        {
+            const VoxelForgeCoreShared::FColumnCacheKey key{
+                static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&recipe)),
+                recipe.contentHash,
+                static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&plan)),
+                plan.contentHash,SampleX,SampleY,island.stableId};
+            bool computed=false;
+            Entry=shared->getOrCompute(key,build,computed);
+        }
+        else Entry=build();
+        *Replacement=Entry;
+        return *Replacement;
     }
 
     inline std::int64_t ScaledQ16(std::int64_t value, std::int64_t scaleQ16)
@@ -641,6 +673,7 @@ namespace floating_island_detail
     }
 
     inline double IslandDensity(const FloatingIslandRecipeV1& recipe,
+                                const FloatingIslandPlanV1& plan,
                                 const FloatingIslandAnchorV1& island,
                                 double x, double y, double z)
     {
@@ -665,7 +698,7 @@ namespace floating_island_detail
                 std::max({z - top, radial - envelope, bottomZ - z}), x, y, z);
         }
 
-        const FIslandColumnCacheEntry& Column=IslandColumnCache(recipe,island,x,y);
+        const FIslandColumnCacheEntry& Column=IslandColumnCache(recipe,plan,island,x,y);
         const double dx=Column.DeltaX;
         const double dy=Column.DeltaY;
         const double radial=Column.Radial;
@@ -733,7 +766,7 @@ namespace floating_island_detail
         double result = static_cast<double>(MaxDensity);
         for (const auto& island : plan.islands)
         {
-            double group = IslandDensity(recipe, island,
+            double group = IslandDensity(recipe, plan, island,
                 static_cast<double>(x), static_cast<double>(y), static_cast<double>(z));
             for (const auto& edge : plan.clusterEdges)
             {
@@ -769,7 +802,7 @@ namespace floating_island_detail
         const auto evaluateLocalGroup = [&](std::size_t islandIndex)
         {
             const auto& island = plan.islands[islandIndex];
-            double group = IslandDensity(recipe, island,
+            double group = IslandDensity(recipe, plan, island,
                 static_cast<double>(x), static_cast<double>(y), static_cast<double>(z));
             for (const std::uint32_t edgeIndex : featureIndices)
             {
@@ -795,7 +828,7 @@ namespace floating_island_detail
         const auto evaluateDistantGroup = [&](std::size_t islandIndex)
         {
             const auto& island = plan.islands[islandIndex];
-            double group = IslandDensity(recipe, island,
+            double group = IslandDensity(recipe, plan, island,
                 static_cast<double>(x), static_cast<double>(y), static_cast<double>(z));
             for (const auto& edge : plan.clusterEdges)
             {

Standalone/Core/src/VoxelForgeCore.cpp

@@ -943,6 +943,10 @@ namespace VoxelForgeCore
         std::shared_ptr<const WorldAssemblyManifest> worldAssembly;
         WorldConfiguration configuration;
         std::unique_ptr<FStandaloneShapeWorld> shape;
+        std::unique_ptr<world_assembly_detail::FSharedHeightfieldColumnCache>
+            sharedHeightfieldColumns;
+        std::unique_ptr<floating_island_detail::FSharedIslandColumnCache>
+            sharedIslandColumns;
         ShapeBuildRequest buildRequest;
         mutable std::shared_mutex tileRegionMutex;
         std::unordered_map<TileKey,std::shared_ptr<FStandaloneShapeWorld>,TileKeyHash> tileRegions;
@@ -953,6 +957,23 @@ namespace VoxelForgeCore
         std::uint64_t lastSequence=0;
     };
 
+    struct FScopedSharedColumnCaches
+    {
+        using FHeightfieldCache=world_assembly_detail::FSharedHeightfieldColumnCache;
+        using FIslandCache=floating_island_detail::FSharedIslandColumnCache;
+        FHeightfieldCache* PreviousHeightfield=nullptr;
+        FIslandCache* PreviousIslands=nullptr;
+
+        FScopedSharedColumnCaches(FHeightfieldCache* Heightfield,FIslandCache* Islands)
+            : PreviousHeightfield(FHeightfieldCache::setThreadActive(Heightfield)),
+              PreviousIslands(FIslandCache::setThreadActive(Islands)) {}
+        ~FScopedSharedColumnCaches()
+        {
+            FHeightfieldCache::setThreadActive(PreviousHeightfield);
+            FIslandCache::setThreadActive(PreviousIslands);
+        }
+    };
+
     World::World(ResolvedWorldSnapshot snapshot):impl_(std::make_unique<Impl>())
     {
         if(snapshot.data_)
@@ -960,6 +981,15 @@ namespace VoxelForgeCore
             impl_->owner=snapshot.data_->owner;
             impl_->worldAssembly=snapshot.data_->worldAssembly;
             impl_->configuration=snapshot.data_->configuration;
+            if(impl_->worldAssembly)
+            {
+                if(!impl_->worldAssembly->plan.strates.empty())
+                    impl_->sharedHeightfieldColumns=
+                        std::make_unique<world_assembly_detail::FSharedHeightfieldColumnCache>();
+                if(!impl_->worldAssembly->floatingIslands.empty())
+                    impl_->sharedIslandColumns=
+                        std::make_unique<floating_island_detail::FSharedIslandColumnCache>();
+            }
         }
     }
     World::~World()=default;
@@ -1337,6 +1367,9 @@ namespace VoxelForgeCore
             options.legacyDirectMappedColumnCache||key.lod<=2);
         if(!impl_||!impl_->owner||!impl_->shape||!impl_->shape->IsBuilt())
         { error="world must be compiled before generating tiles";return std::nullopt; }
+        FScopedSharedColumnCaches sharedColumnCaches(options.useSharedColumnCache
+                ?impl_->sharedHeightfieldColumns.get():nullptr,
+            options.useSharedColumnCache?impl_->sharedIslandColumns.get():nullptr);
         const auto& world=*impl_->owner;
         std::shared_ptr<FStandaloneShapeWorld> page;
         if(impl_->tileRegionCount.load(std::memory_order_acquire)!=0)
@@ -1500,6 +1533,15 @@ namespace VoxelForgeCore
         FStandaloneShapeWorld::ResetThreadClassificationStats();
         VoxelForgeCore::Heightfield2D::resetThreadColumnCacheStats(
             options.captureColumnCoordinates);
+        if(options.captureColumnCoordinates)
+        {
+            constexpr std::int64_t SubvoxelsPerVoxel=WorldAssemblySubvoxelsPerVoxel;
+            VoxelForgeCore::Heightfield2D::setThreadColumnCaptureBounds(
+                static_cast<std::int64_t>(origin.X)*SubvoxelsPerVoxel,
+                static_cast<std::int64_t>(origin.Y)*SubvoxelsPerVoxel,
+                static_cast<std::int64_t>(origin.X+extent)*SubvoxelsPerVoxel,
+                static_cast<std::int64_t>(origin.Y+extent)*SubvoxelsPerVoxel);
+        }
         bool bNativeSurfaceTile=false;
         bool bNativeSurfaceBandSafe=false;
         double classificationColumnComputeMilliseconds=0.0;
@@ -1544,6 +1586,8 @@ namespace VoxelForgeCore
                     out.diagnostics.columnCacheHits=Columns.columnHits;
                     out.diagnostics.columnCacheMisses=Columns.columnMisses;
                     out.diagnostics.columnCacheConflictMisses=Columns.columnConflictMisses;
+                    out.diagnostics.sharedColumnCacheHits=Columns.sharedColumnHits;
+                    out.diagnostics.columnEvaluations=Columns.columnEvaluations;
                     out.diagnostics.classificationMilliseconds=Counts.Milliseconds;
                     out.diagnostics.classificationExclusiveMilliseconds=std::max(0.0,
                         Counts.Milliseconds-classificationColumnComputeMilliseconds);
@@ -1829,6 +1873,8 @@ namespace VoxelForgeCore
             out.diagnostics.columnCacheHits=Columns.columnHits;
             out.diagnostics.columnCacheMisses=Columns.columnMisses;
             out.diagnostics.columnCacheConflictMisses=Columns.columnConflictMisses;
+            out.diagnostics.sharedColumnCacheHits=Columns.sharedColumnHits;
+            out.diagnostics.columnEvaluations=Columns.columnEvaluations;
             out.diagnostics.columnComputeMilliseconds=Columns.columnComputeMilliseconds;
             out.diagnostics.columnEvaluationExclusiveMilliseconds=Columns.columnComputeMilliseconds;
             out.diagnostics.classificationMilliseconds=Counts.Milliseconds;

Standalone/Core/src/WorldAssemblerInternal.h

@@ -5,6 +5,7 @@
 #include "VoxelForgeCore/VoxelForgeCore.h"
 
 #include <algorithm>
+#include <atomic>
 #include <bit>
 #include <charconv>
 #include <chrono>
@@ -121,6 +122,9 @@ WorldAssemblyFeatureColumnRangeV1 BuildWorldAssemblyFeatureColumnRangeV1(
 
 namespace world_assembly_detail
 {
+    using FSharedHeightfieldColumnCache =
+        VoxelForgeCoreShared::TSharedColumnValueCache<HeightfieldPointSample,131072,4>;
+
     // Preserve recipe order without allocating or looking up metadata in the point loop.
     // Garder l'ordre de recette sans allocation ni recherche de metadonnees par point.
     struct FeatureRange
@@ -1375,6 +1379,9 @@ namespace world_assembly_detail
         std::array<std::uint8_t, HeightfieldColumnCacheSetCount>> HeightfieldColumnCacheNextWay;
     inline thread_local HeightfieldColumnCacheStats HeightfieldColumnStats{};
     inline thread_local bool HeightfieldColumnCacheLegacyDirectMapped=false;
+    inline thread_local std::array<std::int64_t,4> HeightfieldColumnCaptureBounds{};
+    inline thread_local bool HeightfieldColumnCaptureBoundsValid=false;
+    inline std::atomic<std::uint64_t> HeightfieldColumnCaptureSequence{0};
 
     inline std::size_t HeightfieldColumnCacheSet(const WorldAssemblyRecipeV1& recipe,
         const WorldAssemblyStratumPlanV1& plan,std::int64_t x,std::int64_t y) noexcept
@@ -1587,22 +1594,46 @@ namespace world_assembly_detail
             replacement=&cache[first+replacementWay];
         }
         auto& entry=*replacement;
-        const auto start=std::chrono::steady_clock::now();
-        HeightfieldPointSample column=EvaluateColumn(recipe,plan,x,y);
-        HeightfieldColumnStats.columnComputeMilliseconds+=std::chrono::duration<double,std::milli>(
-            std::chrono::steady_clock::now()-start).count();
         ++HeightfieldColumnStats.columnMisses;
-        if(HeightfieldColumnStats.captureCoordinates&&HeightfieldColumnStats.coordinateCaptureComplete)
+        const auto compute=[&]()
         {
-            try
+            const std::uint64_t sequence=HeightfieldColumnStats.captureCoordinates
+                ?HeightfieldColumnCaptureSequence.fetch_add(1,std::memory_order_relaxed):0;
+            const auto start=std::chrono::steady_clock::now();
+            HeightfieldPointSample result=EvaluateColumn(recipe,plan,x,y);
+            HeightfieldColumnStats.columnComputeMilliseconds+=std::chrono::duration<double,std::milli>(
+                std::chrono::steady_clock::now()-start).count();
+            ++HeightfieldColumnStats.columnEvaluations;
+            if(HeightfieldColumnStats.captureCoordinates
+                &&HeightfieldColumnStats.coordinateCaptureComplete)
             {
-                HeightfieldColumnStats.evaluatedCoordinates.push_back({x,y});
-            }
-            catch(...)
-            {
-                HeightfieldColumnStats.coordinateCaptureComplete=false;
+                try
+                {
+                    const bool outside=HeightfieldColumnCaptureBoundsValid
+                        &&(x<HeightfieldColumnCaptureBounds[0]||x>HeightfieldColumnCaptureBounds[2]
+                            ||y<HeightfieldColumnCaptureBounds[1]||y>HeightfieldColumnCaptureBounds[3]);
+                    HeightfieldColumnStats.evaluatedCoordinates.push_back({x,y,sequence,outside});
+                }
+                catch(...)
+                {
+                    HeightfieldColumnStats.coordinateCaptureComplete=false;
+                }
             }
+            return result;
+        };
+        HeightfieldPointSample column{};
+        if(auto* shared=FSharedHeightfieldColumnCache::threadActive())
+        {
+            const VoxelForgeCoreShared::FColumnCacheKey key{
+                static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&recipe)),
+                recipe.contentHash,
+                static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(&plan)),
+                plan.contentHash,x,y};
+            bool computed=false;
+            column=shared->getOrCompute(key,compute,computed);
+            if(!computed)++HeightfieldColumnStats.sharedColumnHits;
         }
+        else column=compute();
         entry={&recipe,&plan,recipe.contentHash,plan.contentHash,x,y,column};
         return column;
     }
@@ -2087,10 +2118,22 @@ void Heightfield2D::resetThreadColumnCacheStats(bool captureCoordinates, bool cl
     Stats.columnHits=0;
     Stats.columnMisses=0;
     Stats.columnConflictMisses=0;
+    Stats.sharedColumnHits=0;
+    Stats.columnEvaluations=0;
     Stats.columnComputeMilliseconds=0.0;
     Stats.captureCoordinates=captureCoordinates;
     Stats.coordinateCaptureComplete=true;
     Stats.evaluatedCoordinates.clear();
+    world_assembly_detail::HeightfieldColumnCaptureBoundsValid=false;
+}
+
+void Heightfield2D::setThreadColumnCaptureBounds(std::int64_t minimumXSubvoxels,
+    std::int64_t minimumYSubvoxels,std::int64_t maximumXSubvoxels,
+    std::int64_t maximumYSubvoxels) noexcept
+{
+    world_assembly_detail::HeightfieldColumnCaptureBounds={minimumXSubvoxels,
+        minimumYSubvoxels,maximumXSubvoxels,maximumYSubvoxels};
+    world_assembly_detail::HeightfieldColumnCaptureBoundsValid=true;
 }
 
 void Heightfield2D::setThreadColumnCacheLegacyDirectMapped(bool enabled) noexcept