feat(runner): unify behavior version handling and update to 1.2.0

Author: flemming-n-larsen

CHANGELOG.md

@@ -1,4 +1,4 @@
-## [Unreleased]
+## [1.2.0] - Unreleased - Runner compatibility precondition
 
 ### 🚀 Improvements
 

VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

bot-api/typescript/README.md

@@ -26,7 +26,7 @@ npm install @robocode.dev/tank-royale-bot-api
 To install a specific version:
 
 ```bash
-npm install @robocode.dev/tank-royale-bot-api@1.1.0
+npm install @robocode.dev/tank-royale-bot-api@1.2.0
 ```
 
 The `ws` package is required at runtime in a Node.js environment:

bot-api/typescript/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@robocode.dev/tank-royale-bot-api",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Tank Royale Bot API for TypeScript/JavaScript",
   "license": "Apache-2.0",
   "homepage": "https://robocode-dev.github.io/tank-royale/",

bot-api/typescript/package.json

@@ -4,4 +4,4 @@
  * Do not edit manually — the version is controlled by the /VERSION file in the repository root
  * and stamped into this file by the Gradle `syncVersion` task (same mechanism as package.json).
  */
-export const API_VERSION = "1.1.0";
+export const API_VERSION = "1.2.0";

bot-api/typescript/src/version.ts

@@ -54,9 +54,11 @@ Writing guidelines: be specific (technical detail, not concepts); show your work
 - [ADR-043 — Rumble Client Trust Boundary](ADR-043-rumble-client-trust-boundary.md) · `verified`
 - [ADR-044 — Durable Rumble Result Acknowledgement](ADR-044-durable-rumble-result-acknowledgement.md) · `verified`
 - [ADR-045 — Official Bot API Language Set Is Closed](ADR-045-official-bot-api-language-set.md) · `verified`
+- [ADR-046 — Battle Runner enforces an expected behavior version before bot boot](ADR-046-runner-behavior-version-precondition.md) · `verified` — Ranked Rumble execution must compare the synchronized engine epoch with the running server's handshake before untrusted bot code starts.
 - [IDR-001 — npmPack is the TypeScript publish preview](IDR-001-npm-publish-dry-run.md) · `inferred` — The never-built `npmPublishDryRun` task duplicated the package artifact inspection already provided by `npmPack`.
 - [IDR-002 — TypeScript npm publishing reads the Gradle credential property](IDR-002-npm-publish-credential.md) · `inferred` — Publishing credentials for the repository's package ecosystems are kept in user Gradle properties rather than repository environment configuration.
 - [IDR-003 — The corpus identity ledger is repaired from its own history](IDR-003-identity-ledger-repair.md) · `inferred` — The `CH` counter had drifted from the change identities already bound by the corpus, causing the allocator to reserve an identity that was already in use.
+- [IDR-004 — Rumble client uses the released Battle Runner dependency](IDR-004-rumble-client-battle-runner-dependency.md) · `verified` — CAP-016 requires the Rumble client to execute pinned battles through the Battle Runner API.
 - [PDR-001 — Authorized simple pushes remain distinct from full changes](PDR-001-authorized-simple-pushes.md) · `inferred` — The review boundary must keep accepted-contract changes behind a human-merged pull request while allowing explicitly authorized maintenance work to follow a lighter route.
 - [PDR-002 — Release tooling uses the repository version and verifies documentation locally](PDR-002-release-version-source-and-verification.md) · `inferred` — The Gradle build already owns the repository release version, while generated Pages output is not a checked-in artifact and direct `main` mutation is human-gated.
 - [PDR-003 — The Rumble client waits for the official engine release](PDR-003-rumble-client-release-gate.md) · `inferred` — Ranked Rumble battles must target a published immutable engine distribution rather than unreleased source or a partial runtime contract.
@@ -69,6 +71,4 @@ Writing guidelines: be specific (technical detail, not concepts); show your work
 - [PDR-010 — Design records use the architecture type](PDR-010-design-record-typing.md) · `inferred` — The corpus needs one vocabulary for documents that describe system structure, including the debugging guide and health reports.
 - [PDR-011 — Empty extracted specifications create no capability](PDR-011-empty-extraction-directory.md) · `inferred` — The `browser-sample-bots` OpenSpec directory contained no requirements to preserve.
 - [PDR-012 — Typed decision records replace the legacy decision log](PDR-012-typed-decision-record-carrier.md) · `inferred` — The legacy decision log mixed architecture, process, implementation, and routine history in one carrier that obscured the enduring subject of each choice.
-- [IDR-004 — Rumble client uses the released Battle Runner dependency](IDR-004-rumble-client-battle-runner-dependency.md) · `inferred` — CAP-016 requires the Rumble client to execute pinned battles through the Battle Runner API.
-- [ADR-046 — Battle Runner enforces an expected behavior version before bot boot](ADR-046-runner-behavior-version-precondition.md) · `verified` — Ranked Rumble execution must compare the synchronized engine epoch with the running server's handshake before untrusted bot code starts.
 <!-- clue:index:end -->

docs/decisions/README.md

@@ -52,7 +52,6 @@ import java.util.logging.Logger
  */
 class BattleRunner private constructor(
     val config: Config,
-    internal val requiredBehaviorVersion: Int?,
 ) : AutoCloseable {
 
     private val logger = Logger.getLogger(BattleRunner::class.java.name)
@@ -149,7 +148,7 @@ class BattleRunner private constructor(
             logger.fine("Connecting to server at ${serverManager.serverUrl}...")
             ensureConnected()
             val conn = connection!!
-            requiredBehaviorVersion?.let(conn::requireBehaviorVersion)
+            config.requiredBehaviorVersion?.let(conn::requireBehaviorVersion)
 
             // Capture pre-existing bots (for external server mode)
             val preExistingBots = conn.latestBotList.get().map { it.botAddress }.toSet()
@@ -381,6 +380,11 @@ class BattleRunner private constructor(
          * Defaults to 30 000 ms (30 seconds).
          */
         val botConnectTimeoutMs: Long = 30_000L,
+        /**
+         * Behavior compatibility version the connected server must advertise, or `null` when the
+         * runner accepts any server. Defaults to `null` (unpinned).
+         */
+        val requiredBehaviorVersion: Int? = null,
     )
 
     /** Describes how the server is acquired for this runner instance. */
@@ -500,8 +504,8 @@ class BattleRunner private constructor(
                 recordingPath = recordingPath,
                 captureServerOutput = captureServerOutput,
                 botConnectTimeoutMs = botConnectTimeoutMs,
+                requiredBehaviorVersion = requiredBehaviorVersion,
             ),
-            requiredBehaviorVersion = requiredBehaviorVersion,
         )
     }
 

runner/src/main/kotlin/dev/robocode/tankroyale/runner/BattleRunner.kt

@@ -172,15 +172,15 @@ class BattleRunnerTest {
     fun `behavior version is unpinned by default`() {
         runner = BattleRunner.create { embeddedServer() }
 
-        assertThat(runner!!.requiredBehaviorVersion).isNull()
+        assertThat(runner!!.config.requiredBehaviorVersion).isNull()
     }
 
     @Test
     @Tag("Unit")
     fun `requireBehaviorVersion stores a positive precondition`() {
         runner = BattleRunner.create { embeddedServer(); requireBehaviorVersion(7) }
 
-        assertThat(runner!!.requiredBehaviorVersion).isEqualTo(7)
+        assertThat(runner!!.config.requiredBehaviorVersion).isEqualTo(7)
     }
 
     @Test