Merge pull request #246 from robocode-dev/ch-030-resume-rumble-client

feat(CH-030): require Runner behavior compatibility

Author: flemming-n-larsen

.clue/id-ledger.yaml

@@ -1,13 +1,13 @@
 counters:
-    ADR: "45"
+    ADR: "46"
     AN: "1"
     ARCH: "26"
     C: "4"
     CAP: "17"
-    CH: "29"
+    CH: "30"
     G: "1"
     GTD: "1"
-    IDR: "3"
+    IDR: "4"
     LOG: "1"
     P: "3"
     PDR: "12"
@@ -238,6 +238,11 @@ entries:
       state: live
       prefix: ADR
       component: "45"
+    - id: ADR-046
+      kind: numeric
+      state: live
+      prefix: ADR
+      component: "46"
     - id: AN-001
       kind: numeric
       state: live
@@ -624,6 +629,17 @@ entries:
     - id: CH-029-tasks
       kind: opaque
       state: live
+    - id: CH-030
+      kind: numeric
+      state: live
+      prefix: CH
+      component: "30"
+    - id: CH-030-open-questions
+      kind: opaque
+      state: live
+    - id: CH-030-tasks
+      kind: opaque
+      state: live
     - id: G-001
       kind: numeric
       state: live
@@ -649,6 +665,11 @@ entries:
       state: live
       prefix: IDR
       component: "3"
+    - id: IDR-004
+      kind: numeric
+      state: live
+      prefix: IDR
+      component: "4"
     - id: LOG-001
       kind: numeric
       state: retired

.github/workflows/clue.yml

@@ -7,7 +7,7 @@
 # `clue validate --forbid-changes`, and the full-loop acceptance-brief gate — lives in
 # Cliewen's reusable workflow, so upstream fixes arrive by updating one
 # reference instead of by re-copying steps. Only the triggers below and the
-# four inputs are ours to choose.
+# five inputs are ours to choose.
 #
 # `clue-source: release` downloads the binary from the pinned Cliewen release
 # and verifies it against that release's own SHA256SUMS; this repository
@@ -21,16 +21,19 @@
 # while a SHA names one tree forever. A branch reference must never be used
 # here.
 #
-# The `edited` trigger and the upstream unit's fetch-depth 0 are load-bearing:
-# the acceptance-brief gate must re-run when a pull-request body changes, and
-# change detection needs the base commit.
+# The `edited` and `ready_for_review` triggers and the upstream unit's fetch-depth
+# 0 are load-bearing: the acceptance-brief gate must re-run when a pull-request
+# body changes or a draft becomes a merge candidate, and change detection needs
+# the base commit. With those triggers in place, `draft-aware` lets unfinished
+# drafts retain their transient change workspace without weakening the ready or
+# main-branch gate.
 name: Clue
 
 on:
   push:
     branches: [main]
   pull_request:
-    types: [opened, synchronize, reopened, edited]
+    types: [opened, synchronize, reopened, edited, ready_for_review]
   workflow_dispatch:
 
 permissions:
@@ -45,3 +48,4 @@ jobs:
       clue-version: 0.20.0
       clue-source: release
       clue-install-directory: ''
+      draft-aware: true

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.2.0] - Unreleased - Runner compatibility precondition
+
+### 🚀 Improvements
+
+- Runner:
+    - Added an optional behavior-version precondition that rejects incompatible servers before starting bot processes.
+
 ## [1.1.0] - 2026-08-04 - Rumble foundations
 
 ### 🐞 Bug Fixes

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

@@ -360,4 +360,16 @@ Feature: battle-runner — TBD - created by archiving change add-battle-runner-a
     When the deterministic regression harness runs the same setup and input sequence twice
     Then it SHALL produce byte-for-byte equivalent result snapshots
     And changing one input SHALL change the result snapshot
+
+  # Requirement: Behavior-Version Precondition
+  # A caller may require a server behavior epoch before allowing the Runner to start requested bot processes.
+
+  @BR-049
+  Scenario: Require a compatible server behavior version
+    Test-type: Integration
+    Given a user configures `BattleRunner` with a positive expected behavior version
+    When the Runner connects its observer and controller roles to the server
+    Then both handshakes SHALL advertise the same behavior version
+    And the advertised value SHALL equal the expected version before the Runner starts any requested bot process
+    And a missing, inconsistent, or mismatched value SHALL fail the battle with a descriptive `BattleException`
 ```

docs/capabilities/CAP-001-battle-runner/criteria.md

@@ -0,0 +1,25 @@
+---
+id: ADR-046
+type: decision
+status: verified
+links: [CAP-001, CAP-016, ADR-042]
+title: Battle Runner enforces an expected behavior version before bot boot
+author: agent
+accepted-by: Flemming N. Larsen (2026-08-29, Codex conversation)
+---
+
+# ADR-046 — Battle Runner enforces an expected behavior version before bot boot
+
+## Context
+
+Ranked Rumble execution must compare the synchronized engine epoch with the running server's handshake before the Runner starts the requested untrusted bot code. Battle Runner receives the server handshake internally but previously exposed no way for a caller to require its `behaviorVersion`.
+
+## Decision
+
+Battle Runner adds an optional `requireBehaviorVersion(int)` builder precondition. When configured, the Runner requires both role handshakes to advertise the same positive value and requires that value to equal the expected version after connection but before the Runner starts the requested bot processes. A missing, inconsistent, or mismatched value fails the battle with `BattleException`.
+
+The default remains unpinned for backward compatibility. The API does not expose unrelated handshake fields or infer behavior compatibility from the Tank Royale release version.
+
+## Consequences
+
+Rumble Client can delegate fail-closed compatibility enforcement to the component that owns the server connection. Existing Runner callers retain their current behavior, while callers that require an epoch must opt in explicitly. The API must ship in a released Runner artifact before the external client can depend on it.