measure(step2b): per-brick setup rebuilds the chunk caches -- 10x slower; live cost attributed

Editor-only brick API (<= 8^3 points per call, TunnelNetwork/Underwater op-stack routes, 1.16%
scalar fallback). Exact: 0 Q16/sign disagreements on the full 259^3 ring and the five-seed probe
set, same hash on 1 and 6 workers, reach shrink still caught (18,107 Q16 / 735 sign).
Speed: 69.19 s wall, 17.6 us/sample vs live 7.04 s, 1.65 us/sample. Stack sampler (inclusive):
BuildChunkCache 93.5%, PropagateSdfOverBox 92.5%, BuildActiveOpList 92.6% -- each brick rebuilds
the cache windows and active-op lists; EvalBlock itself is 3.6%.
Live path attribution (inclusive, 68,934 stacks): op-stack RoomGraph EvalBlock 54.4%, SDF and
spatial candidate scans ~28%, tunnel core 18.4%, passage floor segment 15.0%, structural posts
14.6%, noise octaves 2.6%, disturbances 0.6%, diff layer 0.3%.

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

Source/VoxelForgeEditor/Private/VoxelForgeExploreCommandlet.cpp

@@ -1475,6 +1475,40 @@ struct FRegionEvalPass
     FString EndedUtc;
 };
 
+struct FRegionEvalStackSamplerSession
+{
+    bool bStarted = false;
+
+    ~FRegionEvalStackSamplerSession()
+    {
+        if (bStarted)
+        {
+            FVoxelStackSampler::Get().StopAndWrite();
+        }
+    }
+
+    bool Start(uint32 IntervalUs, const FString& OutputDirectory,
+               const TCHAR* Scenario = TEXT("region_eval_live_ring"))
+    {
+        bStarted = FVoxelStackSampler::Get().Start(
+            IntervalUs, OutputDirectory, Scenario);
+        return bStarted;
+    }
+
+    bool Stop(FVoxelStackSampler::FSummary& OutSummary)
+    {
+        if (!bStarted)
+        {
+            return false;
+        }
+        OutSummary = FVoxelStackSampler::Get().StopAndWrite();
+        bStarted = false;
+        return OutSummary.bOutputWritten
+            && OutSummary.RegisteredThreadSamples > 0
+            && OutSummary.RetainedSamples > 0;
+    }
+};
+
 int32 FindRoomGraphRecipeIndex(int32 Seed)
 {
     for (int32 Index = 0; Index < 64; ++Index)
@@ -1724,6 +1758,7 @@ bool RunRegionEvalPass(
     const FExploreArguments& BaseArguments,
     int32 Seed,
     bool bPrepared,
+    bool bBrickProgram,
     float ReachScale,
     bool bFullRing,
     const TArray<int64>* RequestedIndices,
@@ -1731,7 +1766,8 @@ bool RunRegionEvalPass(
     bool bCountCandidates,
     bool bKeepDensities,
     FRegionEvalPass& OutPass,
-    FString& OutError)
+    FString& OutError,
+    int32 RequestedWorkerCount = VoxelForgeRegionEval::WorkerCount)
 {
     OutPass = FRegionEvalPass();
     FExploreWorld World;
@@ -1773,7 +1809,7 @@ bool RunRegionEvalPass(
         bFullRing ? nullptr : &OutPass.SampleIndices,
         bFullRing, bPrepared, ReachScale,
         bKeepDensities ? &OutPass.Densities : nullptr,
-        OutPass.Timing);
+        OutPass.Timing, bBrickProgram, RequestedWorkerCount);
     OutPass.EndedUtc = FDateTime::UtcNow().ToIso8601();
     if (!bEvaluated)
     {
@@ -1799,19 +1835,27 @@ bool RunRegionEvalPass(
 TSharedRef<FJsonObject> RegionEvalTimingJson(const FRegionEvalPass& Pass, bool bPrepared)
 {
     TSharedRef<FJsonObject> Json = MakeShared<FJsonObject>();
-    Json->SetStringField(TEXT("path"), bPrepared ? TEXT("prepared_8cube_bins") : TEXT("live_GetDensityAt"));
+    Json->SetStringField(TEXT("path"), Pass.Timing.bBrickProgram
+        ? TEXT("editor_region_brick_program")
+        : (bPrepared ? TEXT("prepared_8cube_bins") : TEXT("live_GetDensityAt")));
     Json->SetStringField(TEXT("started_utc"), Pass.StartedUtc);
     Json->SetStringField(TEXT("ended_utc"), Pass.EndedUtc);
     Json->SetNumberField(TEXT("worker_count"), Pass.Timing.Workers);
     Json->SetNumberField(TEXT("observed_worker_threads"), Pass.Timing.ObservedWorkerThreads);
     Json->SetNumberField(TEXT("samples"), static_cast<double>(Pass.Timing.SampleCount));
+    Json->SetNumberField(TEXT("evaluated_brick_points"), static_cast<double>(Pass.Timing.EvaluatedSamples));
+    Json->SetNumberField(TEXT("brick_count"), static_cast<double>(Pass.Timing.BrickCount));
+    Json->SetNumberField(TEXT("fallback_points"), static_cast<double>(Pass.Timing.FallbackSamples));
+    Json->SetNumberField(TEXT("fallback_share"), Pass.Timing.FallbackShare);
     Json->SetNumberField(TEXT("world_setup_seconds_before_density_ring"), Pass.WorldPrepareSeconds);
     Json->SetNumberField(TEXT("wall_seconds"), Pass.Timing.WallSeconds);
     Json->SetNumberField(TEXT("worker_cpu_seconds"), Pass.Timing.WorkerCpuSeconds);
     Json->SetNumberField(TEXT("worker_cpu_ns_per_sample"), Pass.Timing.NanosecondsPerSample);
-    Json->SetStringField(TEXT("worker_cpu_source"), Pass.Timing.bWorkerCpuFromOsThreadTimes
-        ? TEXT("summed Windows GetThreadTimes user+kernel CPU across six fixed work partitions")
-        : TEXT("summed worker elapsed fallback; OS thread CPU counters unavailable"));
+    const FString WorkerCpuSource = Pass.Timing.bWorkerCpuFromOsThreadTimes
+        ? FString::Printf(TEXT("summed Windows GetThreadTimes user+kernel CPU across %d fixed work partitions"),
+            Pass.Timing.Workers)
+        : TEXT("summed worker elapsed fallback; OS thread CPU counters unavailable");
+    Json->SetStringField(TEXT("worker_cpu_source"), WorkerCpuSource);
     Json->SetStringField(TEXT("quantized_hash_fnv1a64"),
         FString::Printf(TEXT("%016llx"), static_cast<unsigned long long>(Pass.Timing.QuantizedHash)));
     Json->SetStringField(TEXT("raw_float_hash_fnv1a64"),
@@ -1910,8 +1954,112 @@ int32 RunRegionEval(const FString& Params)
     int32 RequestedSamples = 262144;
     FParse::Value(*Params, TEXT("regionsamples="), RequestedSamples);
     RequestedSamples = FMath::Clamp(RequestedSamples, 32768, 1000000);
+    int32 RequestedWorkerCount = VoxelForgeRegionEval::WorkerCount;
+    FParse::Value(*Params, TEXT("regionworkers="), RequestedWorkerCount);
+    RequestedWorkerCount = FMath::Clamp(RequestedWorkerCount, 1, 32);
     IFileManager::Get().MakeDirectory(*Arguments.OutDirectory, true);
 
+    if (FParse::Param(*Params, TEXT("regionhashprobe")))
+    {
+        FRegionEvalStackSamplerSession WorkerHashStackSampler;
+        if (Arguments.bSampleStacks
+            && !WorkerHashStackSampler.Start(
+                Arguments.SampleStacksIntervalUs, Arguments.OutDirectory,
+                TEXT("region_eval_brick_worker_hash")))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] worker hash stack sampler could not be started."));
+            return 2;
+        }
+
+        FRegionEvalPass WorkerHashPass;
+        const bool bHashPassSucceeded = RunRegionEvalPass(
+                Arguments, 1337, true, true, 1.0f, true, nullptr,
+                RequestedSamples, false, true, WorkerHashPass, Error,
+                RequestedWorkerCount);
+        bool bStackCaptureSucceeded = true;
+        if (Arguments.bSampleStacks)
+        {
+            FVoxelStackSampler::FSummary StackSummary;
+            bStackCaptureSucceeded = WorkerHashStackSampler.Stop(StackSummary);
+            UE_LOG(LogTemp, Display,
+                TEXT("[VoxelForgeRegionEval] worker-hash stack capture registered=%llu retained=%llu "
+                     "raw=%s summary=%s"),
+                static_cast<unsigned long long>(StackSummary.RegisteredThreadSamples),
+                static_cast<unsigned long long>(StackSummary.RetainedSamples),
+                *StackSummary.RawSamplesPath, *StackSummary.SummaryPath);
+        }
+        if (!bHashPassSucceeded || !bStackCaptureSucceeded)
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] worker hash probe failed: %s"),
+                Error.IsEmpty() ? TEXT("stack capture retained no worker samples") : *Error);
+            return 2;
+        }
+
+        FString ReferenceRawHash;
+        FParse::Value(*Params, TEXT("regionreferencehash="), ReferenceRawHash);
+        const FString ActualRawHash = FString::Printf(TEXT("%016llx"),
+            static_cast<unsigned long long>(WorkerHashPass.Timing.RawFloatHash));
+        const bool bHasReferenceHash = !ReferenceRawHash.IsEmpty();
+        const bool bMatchesReference = bHasReferenceHash
+            && ActualRawHash.Equals(ReferenceRawHash, ESearchCase::IgnoreCase);
+        const bool bProbePassed = bMatchesReference
+            && WorkerHashPass.Timing.SampleCount
+                == static_cast<int64>(VoxelForgeRegionEval::RingDimension)
+                    * VoxelForgeRegionEval::RingDimension * VoxelForgeRegionEval::RingDimension
+            && WorkerHashPass.Timing.SaturatedSamples == 0
+            && WorkerHashPass.Timing.NonFiniteSamples == 0;
+
+        TSharedRef<FJsonObject> ProbeReport = MakeShared<FJsonObject>();
+        ProbeReport->SetBoolField(TEXT("pass"), bProbePassed);
+        ProbeReport->SetBoolField(TEXT("worker_count_hash_probe"), true);
+        ProbeReport->SetNumberField(TEXT("worker_count"), WorkerHashPass.Timing.Workers);
+        ProbeReport->SetNumberField(TEXT("observed_worker_threads"),
+            WorkerHashPass.Timing.ObservedWorkerThreads);
+        ProbeReport->SetNumberField(TEXT("samples"), WorkerHashPass.Timing.SampleCount);
+        ProbeReport->SetNumberField(TEXT("brick_count"), WorkerHashPass.Timing.BrickCount);
+        ProbeReport->SetNumberField(TEXT("fallback_points"), WorkerHashPass.Timing.FallbackSamples);
+        ProbeReport->SetNumberField(TEXT("fallback_share"), WorkerHashPass.Timing.FallbackShare);
+        ProbeReport->SetNumberField(TEXT("wall_seconds"), WorkerHashPass.Timing.WallSeconds);
+        ProbeReport->SetNumberField(TEXT("worker_cpu_seconds"), WorkerHashPass.Timing.WorkerCpuSeconds);
+        ProbeReport->SetStringField(TEXT("reference_raw_float_hash_fnv1a64"), ReferenceRawHash);
+        ProbeReport->SetStringField(TEXT("raw_float_hash_fnv1a64"), ActualRawHash);
+        ProbeReport->SetBoolField(TEXT("matches_reference"), bMatchesReference);
+
+        FString ProbeJsonText;
+        TSharedRef<TJsonWriter<>> ProbeWriter = TJsonWriterFactory<>::Create(&ProbeJsonText);
+        if (!FJsonSerializer::Serialize(ProbeReport, ProbeWriter)
+            || !FFileHelper::SaveStringToFile(
+                ProbeJsonText, *FPaths::Combine(Arguments.OutDirectory, TEXT("region_eval.json")),
+                FFileHelper::EEncodingOptions::ForceUTF8WithoutBOM))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] could not write worker hash probe report."));
+            return 2;
+        }
+        UE_LOG(LogTemp, Display,
+            TEXT("[VoxelForgeRegionEval] worker hash probe workers=%d observed=%d samples=%lld "
+                 "raw=%s reference_match=%s report=%s"),
+            WorkerHashPass.Timing.Workers, WorkerHashPass.Timing.ObservedWorkerThreads,
+            static_cast<long long>(WorkerHashPass.Timing.SampleCount), *ActualRawHash,
+            bMatchesReference ? TEXT("yes") : TEXT("no"),
+            *FPaths::Combine(Arguments.OutDirectory, TEXT("region_eval.json")));
+        return bProbePassed ? 0 : 2;
+    }
+
+    // Region-eval returns before the normal Explore sampler setup. Capture only its two cold live
+    // ring trials so prepared-path and multi-seed work cannot pollute the baseline attribution.
+    FRegionEvalStackSamplerSession StackSamplerSession;
+    if (Arguments.bSampleStacks
+        && !StackSamplerSession.Start(
+            Arguments.SampleStacksIntervalUs, Arguments.OutDirectory))
+    {
+        UE_LOG(LogTemp, Error,
+            TEXT("[VoxelForgeRegionEval] requested stack sampler could not be started."));
+        return 2;
+    }
+
     const int32 Seeds[] = { 1337, 7331, 19427, 30241, 41011 };
     TArray<TSharedPtr<FJsonValue>> SeedReports;
     TArray<TSharedPtr<FJsonValue>> OldTimingReports;
@@ -1938,8 +2086,8 @@ int32 RunRegionEval(const FString& Params)
     {
         FRegionEvalPass Pass;
         const bool bOk = RunRegionEvalPass(
-            Arguments, Seeds[0], false, 1.0f, true, nullptr,
-            RequestedSamples, Trial == 0, true, Pass, Error);
+            Arguments, Seeds[0], false, false, 1.0f, true, nullptr,
+            RequestedSamples, Trial == 0 && !Arguments.bSampleStacks, true, Pass, Error);
         if (!bOk)
         {
             UE_LOG(LogTemp, Error, TEXT("[VoxelForgeRegionEval] live full-ring trial failed: %s"), *Error);
@@ -1964,6 +2112,22 @@ int32 RunRegionEval(const FString& Params)
         }
         OldTimingReports.Add(MakeShared<FJsonValueObject>(RegionEvalTimingJson(Pass, false)));
     }
+    if (Arguments.bSampleStacks)
+    {
+        FVoxelStackSampler::FSummary StackSummary;
+        if (!StackSamplerSession.Stop(StackSummary))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] stack capture retained no live-ring worker samples."));
+            return 2;
+        }
+        UE_LOG(LogTemp, Display,
+            TEXT("[VoxelForgeRegionEval] live-ring stack capture registered=%llu retained=%llu "
+                 "raw=%s summary=%s"),
+            static_cast<unsigned long long>(StackSummary.RegisteredThreadSamples),
+            static_cast<unsigned long long>(StackSummary.RetainedSamples),
+            *StackSummary.RawSamplesPath, *StackSummary.SummaryPath);
+    }
     if (PrimarySampleIndices.IsEmpty())
     {
         UE_LOG(LogTemp, Error, TEXT("[VoxelForgeRegionEval] primary statistical sample set is empty."));
@@ -1974,7 +2138,7 @@ int32 RunRegionEval(const FString& Params)
     {
         FRegionEvalPass Pass;
         const bool bOk = RunRegionEvalPass(
-            Arguments, Seeds[0], true, 1.0f, true, nullptr,
+            Arguments, Seeds[0], true, true, 1.0f, true, nullptr,
             RequestedSamples, Trial == 0, true, Pass, Error);
         if (!bOk)
         {
@@ -2003,11 +2167,46 @@ int32 RunRegionEval(const FString& Params)
     // Statistical fixed-lattice comparisons across four additional independent seeds. The sample
     // set is a deterministic affine permutation of the entire 259^3 ring plus dense strata,
     // passage-floor, landing, carve, and fill probes.
+    if (Arguments.bSampleStacks)
+    {
+        FRegionEvalStackSamplerSession BrickStackSamplerSession;
+        if (!BrickStackSamplerSession.Start(
+                Arguments.SampleStacksIntervalUs, Arguments.OutDirectory,
+                TEXT("region_eval_brick_ring")))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] brick stack sampler could not be started."));
+            return 2;
+        }
+        FRegionEvalPass ProfiledBrickPass;
+        if (!RunRegionEvalPass(
+                Arguments, Seeds[0], true, true, 1.0f, true, nullptr,
+                RequestedSamples, false, false, ProfiledBrickPass, Error))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] brick attribution run failed: %s"), *Error);
+            return 2;
+        }
+        FVoxelStackSampler::FSummary BrickStackSummary;
+        if (!BrickStackSamplerSession.Stop(BrickStackSummary))
+        {
+            UE_LOG(LogTemp, Error,
+                TEXT("[VoxelForgeRegionEval] brick stack capture retained no worker samples."));
+            return 2;
+        }
+        UE_LOG(LogTemp, Display,
+            TEXT("[VoxelForgeRegionEval] brick stack capture registered=%llu retained=%llu "
+                 "raw=%s summary=%s"),
+            static_cast<unsigned long long>(BrickStackSummary.RegisteredThreadSamples),
+            static_cast<unsigned long long>(BrickStackSummary.RetainedSamples),
+            *BrickStackSummary.RawSamplesPath, *BrickStackSummary.SummaryPath);
+    }
+
     for (int32 SeedIndex = 1; SeedIndex < UE_ARRAY_COUNT(Seeds); ++SeedIndex)
     {
         FRegionEvalPass OldPass;
         if (!RunRegionEvalPass(
-                Arguments, Seeds[SeedIndex], false, 1.0f, false, nullptr,
+                Arguments, Seeds[SeedIndex], false, false, 1.0f, false, nullptr,
                 RequestedSamples, true, true, OldPass, Error))
         {
             UE_LOG(LogTemp, Error, TEXT("[VoxelForgeRegionEval] seed %d live sample failed: %s"),
@@ -2017,7 +2216,7 @@ int32 RunRegionEval(const FString& Params)
         CollectGarbage(GARBAGE_COLLECTION_KEEPFLAGS);
         FRegionEvalPass NewPass;
         if (!RunRegionEvalPass(
-                Arguments, Seeds[SeedIndex], true, 1.0f, false, &OldPass.SampleIndices,
+                Arguments, Seeds[SeedIndex], true, true, 1.0f, false, &OldPass.SampleIndices,
                 RequestedSamples, true, true, NewPass, Error))
         {
             UE_LOG(LogTemp, Error, TEXT("[VoxelForgeRegionEval] seed %d prepared sample failed: %s"),
@@ -2051,7 +2250,7 @@ int32 RunRegionEval(const FString& Params)
     // commandlet pass and every worker resets it to 1.0 afterward.
     FRegionEvalPass ShrunkPass;
     if (!RunRegionEvalPass(
-            Arguments, Seeds[0], true, 0.50f, false, &PrimarySampleIndices,
+            Arguments, Seeds[0], true, true, 0.50f, false, &PrimarySampleIndices,
             RequestedSamples, false, true, ShrunkPass, Error))
     {
         UE_LOG(LogTemp, Error, TEXT("[VoxelForgeRegionEval] deliberate reach-shrink run failed: %s"), *Error);
@@ -2110,7 +2309,7 @@ int32 RunRegionEval(const FString& Params)
     TSharedRef<FJsonObject> Report = MakeShared<FJsonObject>();
     Report->SetNumberField(TEXT("schema_version"), 1);
     Report->SetStringField(TEXT("route"), TEXT("editor-only explore commandlet; required Unreal composer, manager, and generator types"));
-    Report->SetStringField(TEXT("evaluator"), TEXT("live GetDensityAt final field with editor-only 8^3 SDF room/join/tunnel candidate bins"));
+    Report->SetStringField(TEXT("evaluator"), TEXT("editor-only 8^3 region brick program; block-evaluated composer operator core and canonical per-point final-field writers; unsupported routes use counted live fallbacks"));
     Report->SetStringField(TEXT("comparison_quantization"), TEXT("signed int16; round ties away from zero; multiply density by 16; saturate outside [-2048, 2047.9375] density voxels"));
     Report->SetNumberField(TEXT("worker_count"), VoxelForgeRegionEval::WorkerCount);
     Report->SetNumberField(TEXT("ring_dimension"), VoxelForgeRegionEval::RingDimension);