fix(simulation): PR #210 review round — guard boundary, live oasis pinning, unreachability proof (T-964)

Guard becomes land_districts <= 1 (both reviewers converged — a lone
island definitionally cannot show two distinct directions; same
nothing-to-vary condition one value short), with a lone-island vacuous-
pass fixture; golden confirmed untouched. Oasis scaling adjudicated as
LIVE, not future — GRID_W is already 1024 on main, so ring iterations
change 2/4 -> 4/8 today: extracted a pure oasis_ring_iterations()
helper pinned by tests at both 512 and 1024, and traced exactly why the
determinism hash stayed green (it reads only elevation; the rings touch
only biome — a genuinely different array, not a coincidence). The
drainage merge-logic question answered byte-precisely: zero logic
changed vs main (comment-only diff) — and the deeper dig PROVED the
'isolated basin with another basin to escape to' branch is
mathematically unreachable for any connected grid (contracting vertex
groups of a connected graph cannot disconnect it), so the comment now
states that instead of narrating a divergence that never fires; two
direct merge-target tests added regardless. Wrap test renamed to what
it actually pins (non-wrap-awareness). D-010 docstring softened to
same-process purity, naming the cascade golden as the cross-run layer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tooling/planet-gen/planet_simulation.py

@@ -51,6 +51,26 @@ GRID_W = 1024
 GRID_H = 512
 
 
+def oasis_ring_iterations(grid_w: int) -> tuple[int, int]:
+    """Pixel-unit `binary_dilation` iteration counts for the oasis vegetation
+    ring (T-964, PR #210 review — hoshe), scaled by `grid_w / 512` per the
+    module's GRID_W pixel-unit convention (see the comment above). Base counts
+    (2, 4) are the values authored at the original 512-wide grid; `round(...)`
+    is used (not floor/ceil) so the scaling is symmetric around exact
+    doubling/halving points, and `max(1, ...)` guards against a degenerate
+    zero-iteration dilation at very small `grid_w`.
+
+    Parameterized on `grid_w` (not reading the module-global `GRID_W`
+    directly) so it is independently unit-testable at both the historical
+    512 baseline and the current production 1024 value without needing to
+    monkeypatch the module global.
+    """
+    scale = grid_w / 512.0
+    ring1_iters = max(1, round(2 * scale))
+    ring2_iters = max(1, round(4 * scale))
+    return ring1_iters, ring2_iters
+
+
 # ---------------------------------------------------------------------------
 # Seeded RNG
 # ---------------------------------------------------------------------------
@@ -789,9 +809,13 @@ def compute_biome(body_def, elevation, sea_level, surface_water,
             # ring covers the same physical distance at any resolution — a
             # fixed pixel count would shrink the ring (relative to the
             # planet's real size) as GRID_W grows past the 512 baseline.
-            scale = GRID_W / 512.0
-            ring1_iters = max(1, round(2 * scale))
-            ring2_iters = max(1, round(4 * scale))
+            # LIVE BEHAVIOR CHANGE (T-964, PR #210 review — hoshe): GRID_W is
+            # ALREADY 1024 in production (not a future value), so this scales
+            # ring1/ring2 from the historical 2/4 iterations to 4/8 on EVERY
+            # planet generated today — see `oasis_ring_iterations`'s test
+            # coverage (`test_planet_simulation.py`) pinning both the 512
+            # (historical) and 1024 (current production) values explicitly.
+            ring1_iters, ring2_iters = oasis_ring_iterations(GRID_W)
             ring1 = binary_dilation(oasis_water, iterations=ring1_iters) & ~oasis_water & land
             ring2 = (
                 binary_dilation(oasis_water, iterations=ring2_iters)

tooling/planet-gen/test_oasis_ring_scaling.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Unit tests for `planet_simulation.oasis_ring_iterations` (T-964, PR #210
+review — hoshe).
+
+GRID_W is ALREADY 1024 in production (not a future value) — this pins the
+`binary_dilation` iteration counts the oasis-vegetation-ring code actually
+uses TODAY (4/8), not just the historical 512-baseline values (2/4) the
+original authored constants were tuned at. See the module docstring on
+`oasis_ring_iterations` in `planet_simulation.py` for the scaling rationale.
+
+Pure arithmetic (no numpy/scipy dependency) — stdlib `unittest` only. Run
+directly or via `make test-tooling`:
+  python3 tooling/planet-gen/test_oasis_ring_scaling.py
+"""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from planet_simulation import GRID_W, oasis_ring_iterations  # noqa: E402
+
+
+class OasisRingScalingTests(unittest.TestCase):
+    def test_historical_512_baseline_yields_authored_2_and_4(self):
+        # The values the oasis-ring code was originally authored/tuned at.
+        self.assertEqual(oasis_ring_iterations(512), (2, 4))
+
+    def test_current_production_1024_doubles_to_4_and_8(self):
+        # GRID_W is 1024 in production TODAY (T-964 finding, PR #210 review) —
+        # this is the LIVE behavior every planet generation run exercises now,
+        # not a future/hypothetical value.
+        self.assertEqual(oasis_ring_iterations(1024), (4, 8))
+
+    def test_matches_the_actual_module_global_grid_w(self):
+        # Fixture sanity: whatever GRID_W the module currently declares must
+        # be the value this test suite is pinning against — if GRID_W ever
+        # changes again, this test (not just the two explicit-value tests
+        # above) will fail, forcing the new value to be pinned deliberately.
+        self.assertEqual(GRID_W, 1024)
+
+    def test_minimum_one_iteration_guard_at_a_small_grid_width(self):
+        # A degenerate small grid_w must never round down to 0 iterations
+        # (binary_dilation(iterations=0) is a no-op, silently disabling the
+        # vegetation ring rather than erroring).
+        ring1, ring2 = oasis_ring_iterations(1)
+        self.assertGreaterEqual(ring1, 1)
+        self.assertGreaterEqual(ring2, 1)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)