fix: first /level after zero scan adopts live total as canonical baseline

Diagnostics from a series of /po create + /po reset + /level runs
surfaced three distinct sources of fresh-island drift that the per-chunk
self-heal couldn't close on its own:

1. Spawner entity and chest content values are added to results.rawBlockCount
   in the post-scan handle* phase, not inside scanAsync's bracket, so they
   never make it into scannedChunkValues. A scan with 14 spawners leaves
   exactly 14 * 50 = 700 points of follow-up floating in totalPoints but
   absent from the per-chunk map — which is the 700 the user saw appear
   as level 7 in the first scan of one test.

2. Block-level evolution inside already-known chunks (lava+water forming
   obsidian after the zero scan snapshot, fluid sim propagating, trial
   spawner state) shows up as growing chunks (+821 in one diagnostic)
   that frozen-once won't absorb.

3. When the regular scan races the zero scan on a shared awaitPendingZeros
   counter and runs tidyUp first, persisted is still empty and the
   reconcile credits everything as new — but only at block-only values,
   leaving the entity/chest gap visible as level. (Seen as new=625 in
   the first scan of scenario 3, before zero scan's reconcile had fired.)

Closing all three with one mechanism instead of trying to plug each:
the zero scan now flags handicapPending=true and the next regular scan
adopts its live totalPoints (which already includes spawners, chests,
furniture, evolution) as the persisted initialCount. Subsequent scans
see handicapPending=false and use the normal frozen-once self-heal, so
player builds count toward level as before. The same flag is also set
by the fresh-island reconcile branch (empty map + zero initialCount),
so a regular scan that wins the race against zero scan still produces
level=0 the first time. Legacy migration (empty map + positive
initialCount) explicitly does NOT set the flag, preserving established
player progress across the upgrade.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tastybento

src/main/java/world/bentobox/level/LevelsManager.java

@@ -749,9 +749,14 @@ public long reconcileHandicapChunks(@NonNull Island island,
         if (zeroScan) {
             // Hard reset — the new baseline is everything the scan saw. The
             // initial count is rewritten separately by the caller, since a
-            // zero scan is meant to be the canonical re-baseline.
+            // zero scan is meant to be the canonical re-baseline. Flag
+            // handicapPending so the next regular scan adopts its live total
+            // as the final baseline — that's what absorbs decoration
+            // evolution, spawner/chest follow-up values, and any
+            // listener-deferred chunks the per-chunk capture missed.
             persisted.clear();
             persisted.putAll(scannedChunkValues);
+            data.setHandicapPending(Boolean.TRUE);
             handler.saveObjectAsync(data);
             return 0L;
         }
@@ -762,11 +767,22 @@ public long reconcileHandicapChunks(@NonNull Island island,
                 // feature existed. The existing initialCount already covers
                 // every chunk currently on disk, so seeding the map without
                 // touching initialCount keeps the level stable while moving
-                // future drift detection onto the per-chunk path.
+                // future drift detection onto the per-chunk path. Don't
+                // flip handicapPending here — that would wipe established
+                // player progress on the next /level.
                 persisted.putAll(scannedChunkValues);
                 handler.saveObjectAsync(data);
                 return 0L;
             }
+            // Fresh island whose zero scan either hasn't run yet, hasn't
+            // finalised yet (waiting on awaitPendingZeros), or finished
+            // out-of-order with this regular scan. Flag handicapPending so
+            // tidyUp's baseline finalisation adopts the live total as the
+            // canonical baseline. Without this, the per-chunk reconcile
+            // below seeds the map with block-only values, leaving the
+            // spawner/chest follow-up values floating in totalPoints and
+            // appearing as level on a fresh island.
+            data.setHandicapPending(Boolean.TRUE);
         }
         long delta = 0L;
         int newChunks = 0;

src/main/java/world/bentobox/level/calculators/IslandLevelCalculator.java

@@ -925,6 +925,28 @@ public void tidyUp() {
         long blockAndDeathPoints = this.results.rawBlockCount.get();
         this.results.totalPoints.set(blockAndDeathPoints);
 
+        // First regular scan after a zero scan: adopt the live total as the
+        // canonical baseline. The zero scan set handicapPending=true; this
+        // overwrite absorbs decoration evolution, listener-deferred chunks,
+        // spawner/chest follow-up values, and any race between zero scan
+        // and regular scan into one consistent number, so the player sees
+        // level=0 on a fresh island. Subsequent regular scans see
+        // handicapPending=false and use the normal frozen-once handicap so
+        // player builds count toward level.
+        if (!zeroIsland && addon.getSettings().isZeroNewIslandLevels()
+                && !addon.getSettings().isDonationsOnly()) {
+            world.bentobox.level.objects.IslandLevels data =
+                    addon.getManager().getLevelsData(island);
+            if (data != null && Boolean.TRUE.equals(data.getHandicapPending())) {
+                long total = this.results.totalPoints.get();
+                addon.getManager().setInitialIslandCount(island, total);
+                data.setHandicapPending(Boolean.FALSE);
+                results.initialCount.set(total);
+                addon.log("Handicap baseline finalised at " + total
+                        + " for island " + island.getUniqueId());
+            }
+        }
+
         if (this.addon.getSettings().getDeathPenalty() > 0) {
             // Proper death penalty calculation.
             blockAndDeathPoints -= this.results.deathHandicap.get() * this.addon.getSettings().getDeathPenalty();

src/main/java/world/bentobox/level/objects/IslandLevels.java

@@ -119,6 +119,22 @@ public class IslandLevels implements DataObject {
     @Expose
     private Map<String, Long> handicapChunks;
 
+    /**
+     * Set to {@code true} when a zero scan has just populated the handicap
+     * map but the player hasn't run {@code /level} yet; the next regular
+     * scan adopts its live total as the canonical baseline, absorbing any
+     * decoration evolution, listener-deferred chunks, and spawner/chest
+     * follow-up values that fell outside the per-chunk capture. Cleared
+     * back to {@code false} on that overwrite so subsequent scans see the
+     * normal frozen-once handicap.
+     * <p>
+     * Null on legacy data — treated as false, so existing islands aren't
+     * accidentally rebaselined on upgrade (which would wipe player
+     * progress).
+     */
+    @Expose
+    private Boolean handicapPending;
+
     /**
      * Constructor for new island
      * @param islandUUID - island UUID
@@ -393,6 +409,22 @@ public void setHandicapChunks(Map<String, Long> handicapChunks) {
         this.handicapChunks = handicapChunks;
     }
 
+    /**
+     * @return {@code true} if a zero scan has just finished and the next
+     *         regular scan should adopt its live total as the baseline.
+     *         Null on legacy data (treated as false by callers).
+     */
+    public Boolean getHandicapPending() {
+        return handicapPending;
+    }
+
+    /**
+     * @param handicapPending the handicapPending to set
+     */
+    public void setHandicapPending(Boolean handicapPending) {
+        this.handicapPending = handicapPending;
+    }
+
     /**
      * @return the initialLevel
      * @deprecated only used for backwards compatibility. Use {@link #getInitialCount()} instead

src/test/java/world/bentobox/level/LevelsManagerTest.java

@@ -528,6 +528,45 @@ void testReconcileHandicapChunksLegacyMigration() throws Exception {
         assertEquals(100L, legacy.getHandicapChunks().get("world:1"));
     }
 
+    /**
+     * Pin down that zero-scan reconcile sets handicapPending=true and a
+     * fresh-island reconcile (empty map + zero initialCount) does the same.
+     * tidyUp will then adopt the live scan total as the canonical baseline.
+     * Legacy migration (empty map + positive initialCount) must NOT set the
+     * flag — flipping it on an old island would wipe established player
+     * progress on the next /level.
+     */
+    @Test
+    void testReconcileSetsHandicapPendingForBaselineFinalisation() throws Exception {
+        // Zero scan: pending=true so first regular scan overwrites.
+        IslandLevels zeroScanData = new IslandLevels(uuid.toString());
+        when(handler.loadObject(uuid.toString())).thenReturn(zeroScanData);
+        lm.reconcileHandicapChunks(island, Map.of("world:1", 100L), true);
+        assertEquals(Boolean.TRUE, zeroScanData.getHandicapPending(),
+                "zero scan flags the next regular scan for baseline overwrite");
+
+        // Fresh island, no prior scan: pending=true so the very first regular
+        // scan establishes the baseline correctly even if zero scan raced.
+        UUID otherId = UUID.randomUUID();
+        when(island.getUniqueId()).thenReturn(otherId.toString());
+        IslandLevels freshData = new IslandLevels(otherId.toString());
+        when(handler.loadObject(otherId.toString())).thenReturn(freshData);
+        lm.reconcileHandicapChunks(island, Map.of("world:1", 100L), false);
+        assertEquals(Boolean.TRUE, freshData.getHandicapPending(),
+                "fresh-island regular scan flags itself for baseline overwrite");
+
+        // Legacy migration: pending stays null. Old islands keep their
+        // established progress across the upgrade.
+        UUID legacyId = UUID.randomUUID();
+        when(island.getUniqueId()).thenReturn(legacyId.toString());
+        IslandLevels legacyData = new IslandLevels(legacyId.toString());
+        legacyData.setInitialCount(5000L);
+        when(handler.loadObject(legacyId.toString())).thenReturn(legacyData);
+        lm.reconcileHandicapChunks(island, Map.of("world:1", 100L), false);
+        assertEquals(null, legacyData.getHandicapPending(),
+                "legacy migration does NOT flag baseline overwrite");
+    }
+
     /**
      * Zero-scan reconciliation hard-resets the map and returns 0 (the caller
      * rewrites initialCount separately via setInitialIslandCount).