feat(core): profiled heightfields, slice 1: periodicHills, mirroredRelief, flatField (L53); research R22

WorldAssemblySurfaceProfileV1 on the native SurfaceWorld recipe and plan; version 0 'natural' is omitted
from serialized identity, so the owner world is unchanged. periodicHills (seeded cosine hills, plan-time
grade <= 15 deg), mirroredRelief (cap mirrors the floor by lambda, clearance checked) and flatField share
one profile function for points, lattice classification and exact cosine-extrema intervals (0 interval
misses in brute-force audits). Style-override fixtures with planned passages. Cold whole view about 1.33 s
for each profile vs 1.74 s natural SW (Clang). Owner hashes identical to L52; fast/medium/full PASS.
Research R22: SurfaceWorld critical path to about 1 s.

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

Standalone/Source/StreamBenchmarkHeadless.cpp

@@ -56,6 +56,7 @@ namespace
         bool HasRenderDistanceOverride=false;
         int RenderDistanceOverride=0;
         bool FloatingIslandsRecipe=false;
+        bool AuditHeightfieldProfile=false;
         bool LandmarkChamberDemo=false;
         bool LandmarkL45RampControl=false;
         bool OreVeinsDemo=false;
@@ -72,6 +73,7 @@ namespace
         float CameraYawDegrees=0.0f;
         float CameraPitchDegrees=0.0f;
         std::filesystem::path MeshExportPath;
+        std::filesystem::path WorldAssemblyManifestOutputPath;
         std::filesystem::path ResolvedLayoutOutputPath;
         bool ResolvedLayoutOnly=false;
         bool AuditResolvedLayoutBoundaries=false;
@@ -114,6 +116,160 @@ namespace
         return true;
     }
 
+    const char* SurfaceProfileName(VoxelForgeCore::WorldAssemblySurfaceProfileKindV1 kind)
+    {
+        using VoxelForgeCore::WorldAssemblySurfaceProfileKindV1;
+        switch (kind)
+        {
+        case WorldAssemblySurfaceProfileKindV1::periodicHills: return "periodicHills";
+        case WorldAssemblySurfaceProfileKindV1::mirroredRelief: return "mirroredRelief";
+        case WorldAssemblySurfaceProfileKindV1::flatField: return "flatField";
+        default: return "natural";
+        }
+    }
+
+    bool RunHeightfieldProfileAudit(const VoxelForgeCore::WorldAssemblyManifest& assembly)
+    {
+        using namespace VoxelForgeCore;
+        constexpr std::int64_t QPerMetre = WorldAssemblySubvoxelsPerVoxel * 4;
+        constexpr std::int64_t BoxStep = 8 * WorldAssemblySubvoxelsPerVoxel;
+        std::uint64_t strataAudited = 0;
+        bool allPassed = true;
+        for (const auto& stratum : assembly.plan.strates)
+        {
+            const WorldAssemblyRecipeV1& recipe = stratum.hasRecipeOverride
+                ? stratum.recipeOverride : assembly.recipe;
+            const auto& profile = recipe.surfaceProfile;
+            if (profile.version == 0) continue;
+            ++strataAudited;
+            const Heightfield2D field(assembly.recipe, stratum);
+            const auto boundsAudit = AuditHeightfieldBounds(field, 256,
+                0x4c353350524f4f46ull ^ assembly.contentHash ^ stratum.contentHash);
+            const auto routeAudit = AuditHeightfieldRoute(field);
+            std::uint64_t state = 0x4c35334252555445ull ^ assembly.contentHash
+                ^ stratum.contentHash;
+            const auto nextRandom = [&state]()
+            {
+                state += 0x9E3779B97F4A7C15ull;
+                std::uint64_t value = state;
+                value = (value ^ (value >> 30)) * 0xBF58476D1CE4E5B9ull;
+                value = (value ^ (value >> 27)) * 0x94D049BB133111EBull;
+                return value ^ (value >> 31);
+            };
+            std::uint64_t bruteBoxes = 0, bruteSamples = 0;
+            std::uint64_t intervalMisses = 0, classifierMismatches = 0;
+            std::uint64_t certifiedAir = 0, certifiedSolid = 0;
+            for (int boxIndex = 0; boxIndex < 96; ++boxIndex)
+            {
+                const std::int64_t x = (static_cast<std::int64_t>(nextRandom() % 401) - 200)
+                    * QPerMetre;
+                const std::int64_t y = (static_cast<std::int64_t>(nextRandom() % 401) - 200)
+                    * QPerMetre;
+                const std::int64_t span = (8 + static_cast<std::int64_t>(nextRandom() % 5))
+                    * BoxStep;
+                const std::int64_t minX = x, minY = y;
+                const std::int64_t maxX = minX + span, maxY = minY + span;
+                const std::int64_t centerX = minX + span / 2;
+                const std::int64_t centerY = minY + span / 2;
+                const HeightfieldPointSample column = field.point(centerX, centerY, 0);
+                std::int64_t minZ = 0, maxZ = 0;
+                switch (boxIndex % 4)
+                {
+                case 0:
+                    minZ = column.groundHeightSubvoxels - 4 * QPerMetre;
+                    maxZ = column.groundHeightSubvoxels - 2 * QPerMetre;
+                    break;
+                case 1:
+                    minZ = column.groundHeightSubvoxels
+                        + profile.amplitudeXSubvoxels + profile.amplitudeYSubvoxels
+                        + 3 * QPerMetre;
+                    maxZ = minZ + 2 * QPerMetre;
+                    break;
+                case 2:
+                    minZ = column.groundHeightSubvoxels - QPerMetre;
+                    maxZ = column.groundHeightSubvoxels + QPerMetre;
+                    break;
+                default:
+                    minZ = column.capHeightSubvoxels - 2 * QPerMetre;
+                    maxZ = column.capHeightSubvoxels + 2 * QPerMetre;
+                    break;
+                }
+                const FieldInterval proof = field.interval(minX, minY, minZ,
+                    maxX, maxY, maxZ);
+                ++bruteBoxes;
+                if (!proof.known) { ++intervalMisses; continue; }
+                if (proof.minimumDensitySubvoxels > 0) ++certifiedAir;
+                if (proof.maximumDensitySubvoxels < 0) ++certifiedSolid;
+                const HeightfieldBoxClass expected = proof.minimumDensitySubvoxels > 0
+                    ? HeightfieldBoxClass::allAir
+                    : proof.maximumDensitySubvoxels < 0
+                        ? HeightfieldBoxClass::allSolid : HeightfieldBoxClass::mixed;
+                if (field.classifyLatticeBox(minX, minY, minZ, maxX, maxY, maxZ, 8)
+                    != expected) ++classifierMismatches;
+                for (int iz = 0; iz <= 2; ++iz)
+                for (int iy = 0; iy <= 8; ++iy)
+                for (int ix = 0; ix <= 8; ++ix)
+                {
+                    const std::int64_t px = minX + span * ix / 8;
+                    const std::int64_t py = minY + span * iy / 8;
+                    const std::int64_t pz = minZ + (maxZ - minZ) * iz / 2;
+                    const auto sample = field.point(px, py, pz);
+                    ++bruteSamples;
+                    if (sample.densitySubvoxels < proof.minimumDensitySubvoxels
+                        || sample.densitySubvoxels > proof.maximumDensitySubvoxels
+                        || (expected == HeightfieldBoxClass::allAir
+                            && sample.densitySubvoxels <= 0)
+                        || (expected == HeightfieldBoxClass::allSolid
+                            && sample.densitySubvoxels >= 0))
+                        ++intervalMisses;
+                }
+            }
+            const std::int64_t relief = profile.amplitudeXSubvoxels
+                + profile.amplitudeYSubvoxels;
+            std::int64_t capSwing = 0;
+            if (profile.kind == WorldAssemblySurfaceProfileKindV1::mirroredRelief)
+                capSwing = (relief * profile.mirrorLambdaQ16 + 65535) / 65536;
+            const double minimumClearanceMetres = static_cast<double>(
+                stratum.capHeightSubvoxels - capSwing - profile.h0Subvoxels - relief - 4)
+                / QPerMetre;
+            const double requiredClearanceMetres = static_cast<double>(std::max<std::int64_t>(
+                2253, profile.minimumArenaClearanceSubvoxels)) / QPerMetre;
+            const double gx = profile.kind == WorldAssemblySurfaceProfileKindV1::flatField
+                ? 0.0 : 2.0 * std::acos(-1.0)
+                    * profile.amplitudeXSubvoxels / profile.wavelengthXSubvoxels;
+            const double gy = profile.kind == WorldAssemblySurfaceProfileKindV1::flatField
+                ? 0.0 : 2.0 * std::acos(-1.0)
+                    * profile.amplitudeYSubvoxels / profile.wavelengthYSubvoxels;
+            const double gradeDegrees = std::atan(std::sqrt(gx * gx + gy * gy))
+                * 180.0 / std::acos(-1.0);
+            const bool profilePassed = field.isValid() && boundsAudit.passed && routeAudit.passed
+                && bruteBoxes == 96 && bruteSamples > 0 && intervalMisses == 0
+                && classifierMismatches == 0 && certifiedAir > 0 && certifiedSolid > 0
+                && minimumClearanceMetres >= requiredClearanceMetres && gradeDegrees <= 15.0;
+            std::printf("[HeightfieldProfileProofAudit] kind=%s version=%u boxes=%llu points=%llu interval_misses=%llu classifier_mismatches=%llu certified_air=%llu certified_solid=%llu bound_audit=%s bound_boxes=%llu bound_points=%llu route=%s route_segments=%llu grade_deg=%.6f clearance_m=%.6f required_clearance_m=%.6f phase_x_q32=%u phase_y_q32=%u status=%s\n",
+                SurfaceProfileName(profile.kind), profile.version,
+                static_cast<unsigned long long>(bruteBoxes),
+                static_cast<unsigned long long>(bruteSamples),
+                static_cast<unsigned long long>(intervalMisses),
+                static_cast<unsigned long long>(classifierMismatches),
+                static_cast<unsigned long long>(certifiedAir),
+                static_cast<unsigned long long>(certifiedSolid),
+                boundsAudit.passed ? "PASS" : "FAIL",
+                static_cast<unsigned long long>(boundsAudit.boxesTested),
+                static_cast<unsigned long long>(boundsAudit.pointSamples),
+                routeAudit.passed ? "PASS" : "FAIL",
+                static_cast<unsigned long long>(routeAudit.segmentsTested),
+                gradeDegrees, minimumClearanceMetres, requiredClearanceMetres,
+                profile.phaseXTurnsQ32, profile.phaseYTurnsQ32,
+                profilePassed ? "PASS" : "FAIL");
+            allPassed = allPassed && profilePassed;
+        }
+        const bool passed = strataAudited > 0 && allPassed;
+        if (strataAudited == 0)
+            std::printf("[HeightfieldProfileProofAudit] profiles=0 status=FAIL\n");
+        return passed;
+    }
+
     bool MakeLandmarkChamberDemoRequests(
         const VoxelForgeCore::ResolvedLayoutSnapshotV3& layout,
         const VoxelForgeCore::WorldAssemblyManifest& worldAssembly,
@@ -806,6 +962,7 @@ namespace
                     "  --region-crossing (compile entering Core regions at the camera step)\n"
                     "  --column-cache=shared|thread-local (default: shared)\n"
                     "  --mesh-export=FILE (write the exact generated tile meshes for offline rendering)\n"
+                    "  --world-assembler-manifest-output=FILE (write the canonical Core recipe and plan)\n"
                     "  --profile-column-overlap --far-horizon-lod8-step=N --force-generate\n"
                     "  --seed=N --recipe=surface-world|floating-islands\n"
                     "  --landmark-chamber-demo (opt-in SW cavern room and swept tunnel)\n"
@@ -818,6 +975,7 @@ namespace
                     "  --audit-strate-transitions (measure interface crossing, band thickness and holes)\n"
                     "  --transition-mode=hard|gradient|interleaved --transition-width-chunks=N (fixture override)\n"
                     "  --audit-resolved-layout-passages (capsule, support, route-binding and blocked-control audit)\n"
+                    "  --audit-heightfield-profile (brute-force the profiled field intervals and route)\n"
                     "  --audit-landmark-reachability (capsule, support, grade and buried-L43 control)\n"
                     "  --audit-surface-clearance (sample biome terrain/caps against the resolved ceiling)\n"
                     "  --auto-surface-camera (place the 27-tile cube on this seed's surface)\n"
@@ -837,6 +995,10 @@ namespace
                 return false;
             }
             if(arg=="--world-assembler-prototype")options.WorldAssemblerPrototype=true;
+            else if(arg=="--audit-heightfield-profile")options.AuditHeightfieldProfile=true;
+            else if(arg.starts_with("--world-assembler-manifest-output="))
+                options.WorldAssemblyManifestOutputPath=std::filesystem::path(std::string(
+                    arg.substr(std::string_view("--world-assembler-manifest-output=").size())));
             else if(arg=="--resolved-layout-only")options.ResolvedLayoutOnly=true;
             else if(arg=="--audit-resolved-layout-boundaries")options.AuditResolvedLayoutBoundaries=true;
             else if(arg=="--audit-resolved-layout-passages")options.AuditResolvedLayoutPassages=true;
@@ -1052,12 +1214,17 @@ int main(int argc,char** argv)
     const auto planStart=Clock::now();
     VoxelForgeCore::WorldAssemblyManifest worldAssembly;
     if(!StandaloneWorldAssemblyPrototype::AttachRound1WorldAssemblyPrototype(
-        *ownerWorld,ownerJsonRoot,error,{},&worldAssembly))
+        *ownerWorld,ownerJsonRoot,error,options.WorldAssemblyManifestOutputPath.string(),&worldAssembly))
     {std::fprintf(stderr,"World assembler prototype setup failed: %s\n",error.c_str());return 2;}
     if(options.FloatingIslandsRecipe
         &&!StandaloneWorldAssemblyPrototype::AttachFloatingIslandWorldAssembly(
             *ownerWorld,ownerJsonRoot,worldAssembly,error))
     {std::fprintf(stderr,"Floating-island assembly setup failed: %s\n",error.c_str());return 2;}
+    if (options.AuditHeightfieldProfile && !RunHeightfieldProfileAudit(worldAssembly))
+    {
+        std::fprintf(stderr,"Profiled SurfaceWorld interval, classification or route audit failed.\n");
+        return 2;
+    }
     VoxelForgeCore::ResolvedLayoutSnapshotV3 resolvedLayout;
     {
         const std::string_view variant=options.FloatingIslandsRecipe?"floating-islands":"surface-world";