Pin the variable-expansion iteration cap with an oscillating cycle

ExpandTest covered the self-referential cycle (terminates via the
next==result fixpoint break), but not an oscillating two-variable cycle
(%a% to %b% to %a%), which never reaches a fixpoint and instead relies on
the MAX_ITERATIONS cap to terminate. Host-supplied values (chat text read
as a variable) can be adversarially self-referential, so guard that the
cap path does not hang. Test-only, jars unchanged. Doc test count to 362.

Author: jacklau

CONTRIBUTING.md

@@ -28,7 +28,7 @@ Use `./gradlew` (the wrapper) — do not rely on a system Gradle.
 The engine is a normal single Kotlin module. Develop and test it without touching Fabric:
 
 ```bash
-./gradlew :engine:test       # 361 unit tests
+./gradlew :engine:test       # 362 unit tests
 ./gradlew :engine:build
 ```
 

README.md

@@ -23,7 +23,7 @@ first-class support for **23 Minecraft versions**
   own algorithm** through the [Pathfinder SPI](docs/guide/pathfinding.md#write-your-own-pathfinder).
 - **Auto-reconnect** — opt-in: rejoin the last server automatically after a disconnect (toggle
   via the in-game module GUI or a keybind).
-- **Tested** — the engine ships a real unit-test suite (361 tests): lexer, parser, runtime
+- **Tested** — the engine ships a real unit-test suite (362 tests): lexer, parser, runtime
   VM, variables, expressions, actions, pathfinding.
 
 ---
@@ -170,7 +170,7 @@ the full workflow.
 ```
 mc_macromod/
 ├─ engine/          Pure-JVM scripting engine (DSL lexer → compiler → VM, pathfinding,
-│                   modules). No Minecraft deps. 361 unit tests.
+│                   modules). No Minecraft deps. 362 unit tests.
 ├─ fabric/          Multi-version Fabric mod (Stonecutter). Keybinds, MC actions, GUI,
 │                   events, navigation. Shades :engine via Jar-in-Jar.
 │  └─ versions/     Per-Minecraft-version gradle.properties (deps + Java level).

docs/VERSIONS.md

@@ -68,7 +68,7 @@ auto-provisioned by Foojay** on first build.
 > the Java-16 (1.17.1) and Java-8 (1.16.5) variants that shade the engine (JIJ). The engine uses
 > only Kotlin stdlib (`kotlin.collections.ArrayDeque.addFirst` etc.) with no APIs above Java 8,
 > so targeting 8 is behavior-neutral and the Java-8 (major-version-52) bytecode runs on every
-> newer-JVM variant too. `./gradlew :engine:test` stays green at 361 tests.
+> newer-JVM variant too. `./gradlew :engine:test` stays green at 362 tests.
 
 ## Supported versions
 

docs/index.md

@@ -36,7 +36,7 @@ first-class **multi-version** support.
 
     ---
 
-    The engine ships a real unit-test suite (361 tests): lexer, parser, runtime VM,
+    The engine ships a real unit-test suite (362 tests): lexer, parser, runtime VM,
     variables, expressions, actions, pathfinding.
 
 </div>

engine/src/test/kotlin/dev/macromod/engine/param/ExpandTest.kt

@@ -4,6 +4,7 @@ import dev.macromod.engine.value.Value
 import dev.macromod.engine.variable.VariableRegistry
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertTrue
 
 class ExpandTest {
     private fun expander(vararg pairs: Pair<String, Value>): VariableExpander {
@@ -47,6 +48,16 @@ class ExpandTest {
         assertEquals("%&a%", e.expand("%&a%"))
     }
 
+    @Test fun `an oscillating two-variable cycle terminates at the iteration cap`() {
+        // %a% -> "%b%" -> "%a%" -> ... never reaches a fixpoint (the value keeps flipping), so unlike the
+        // self-ref case above it never hits the next==result break — it must terminate via the
+        // MAX_ITERATIONS cap instead. Host-supplied values (e.g. chat text read as a variable) can be
+        // adversarially self-referential, so this path must not hang. The test completing proves it.
+        val e = expander("&a" to Value.Str("%&b%"), "&b" to Value.Str("%&a%"))
+        val out = e.expand("%&a%")
+        assertTrue(out == "%&a%" || out == "%&b%", "expected a residual ref after the cap, got: $out")
+    }
+
     @Test fun `a literal percent sign is left untouched`() {
         assertEquals("100% done", expander().expand("100% done"))
         // the bare "50%" stays literal (no name follows the %); the real ref still expands