robocode-dev · flemming-n-larsen · Aug 4, 2026
@@ -12,7 +12,7 @@ title: Create Rumble Client
 
 Create the community-owned `robocode-dev/rumble-client` repository: a local ranked and practice battle client built on Tank Royale's Battle Runner. In ranked mode it will follow the Rumble data repository's canonical-location and engine-pin records, obtain the synchronized bot catalog and per-game-type matchmaking advice, run the selected battle against the pinned engine, record every completed result in a local journal with replay evidence, and submit batches through the registered-client issue-ops flow. Practice mode will run local battles without creating or submitting any ranked result.
 
-The client will make ranked execution reproducible and intentionally constrained: it will verify schema versions, source hashes, catalog commit, game type, and `behaviorVersion` before a battle; it will preserve unsent journal entries across failures; and it will never receive repository-content, branch, projection, or Git-history write access. A rebuildable container will be the primary distribution and sandbox boundary, with documented bare-metal operation as a fallback.
+The client will make ranked execution reproducible and intentionally constrained: it will verify schema versions, source hashes, catalog commit, game type, and `behaviorVersion` before a battle; it will preserve unsent journal entries across failures; and it will never receive repository-content, branch, projection, or Git-history write access. Contributors may run the client directly on a supported host or use the recommended rebuildable Docker image. The image supplies the pinned multi-runtime environment and separates online synchronization and submission from credential-free, offline battle execution.
 
 ## Why
 
@@ -26,7 +26,7 @@ M-006 supplies the reviewed bot sources and M-007 supplies the engine pin, catal
 - Implement ranked selection for `1v1`, `twinduel`, and `melee`, preferring configured own bots while using seeded selection from published advice without treating advice as a reservation.
 - Integrate the Battle Runner to execute a full pinned battle, transcribe `BattleResults` into the data repository's result-envelope format, hash and retain a local replay, append it to the journal, and reject incompatible engine or catalog state before execution.
 - Implement registered-client issue-ops submission with batch retry/backoff and acknowledgement-driven journal rollover. Define the fork-pull-request transport as the portable fallback where the data-repository contract supports it.
-- Provide a rebuildable, egress-constrained container carrying the pinned Tank Royale runtime and the Java, .NET, Python, and Node.js bot runtimes, with documented bare-metal fallback operation.
+- Provide a rebuildable Docker image carrying the pinned Tank Royale runtime and the Java, .NET, Python, and Node.js bot runtimes, plus a supported native distribution whose preflight checks the same runtime requirements. Docker launchers run synchronization online without credentials, battles without external networking or submission credentials, and submission online without starting bot code.
 - Record M-008 evidence in P-003 only after a registered-client ranked battle reaches `robocode-dev/rumble-data` through issue-ops and its CI ingests it without manual intervention.
 
 ## Non-goals

@@ -13,8 +13,10 @@ title: Task breakdown for CH-012
 - [x] Pause for maintainer approval of this proposal before implementation, as required by the Rumble roadmap
 - [x] Define client capability ownership, contracts, acceptance criteria, and durable decisions in the Tank Royale corpus
 - [x] Resolve durable result acknowledgement so successful receipts follow publication of accepted facts
-- [ ] Create and configure the community-owned `rumble-client` repository with contributor, security, configuration, container, and operating guidance
+- [x] Create and configure the community-owned `rumble-client` repository with contributor, security, configuration, container, and operating guidance
+- [x] Revise the CH-012 runtime-distribution contract so native execution is supported and Docker is the recommended isolated path (RCL-010, RCL-011)
 - [ ] Implement validated synchronization, bot cache preparation, ranked and practice selection, and Battle Runner execution for every V1 game type
 - [ ] Implement local journal and replay-evidence handling, result transcription, and registered-client issue-ops submission with acknowledgement-driven retry and rollover
-- [ ] Add the rebuildable runtime container, bare-metal fallback, and focused positive and negative acceptance evidence, including a fully automated end-to-end ranked submission
+- [ ] Add native distributions, the rebuildable Docker runtime, phased launchers, and focused positive and negative acceptance evidence (RCL-010, RCL-011)
+- [ ] Publish and pin the Docker image only after a Tank Royale release containing the M-005 contracts is available
 - [ ] Record M-008 evidence in P-003, then run the external repository's focused checks, `clue validate`, and `clue-verify`; mark each task as it completes
@@ -14,7 +14,7 @@ The external `robocode-dev/rumble-data` repository owns result storage and proje
 
 ## Input and immutable-fact contracts
 
-`engine.json` pins a positive `behaviorVersion`, Tank Royale release and image references, and ranked settings for `1v1`, `twinduel`, and `melee`. `catalog.json` is the synchronized published bot catalog; only its active name-and-version entries can occur in ranked results. A contributor is admitted by a reviewed `clients/<forge-account>.json` registration that declares stable client IDs.
+`engine.json` pins a positive `behaviorVersion`, Tank Royale release and image references, an optional immutable `clientImage` reference for the recommended Rumble Client Docker distribution, and ranked settings for `1v1`, `twinduel`, and `melee`. The client image is installation guidance rather than the compatibility axis and is published only for a Tank Royale release carrying the Rumble contracts. `catalog.json` is the synchronized published bot catalog; only its active name-and-version entries can occur in ranked results. A contributor is admitted by a reviewed `clients/<forge-account>.json` registration that declares stable client IDs.
 
 An issue-ops submission is one fenced JSON batch envelope with `schemaVersion`, `clientId`, `clientVersion`, and one to sixty result records. Each record includes a UUID `battleId`, completion time, matching nested client identity, behavior version, game type, pinned battle dimensions, and the complete Battle Runner participant result model. The validator checks the contract independently for every record, then normalizes valid records with the submitting account and payload hash. A content-addressed JSON file under `results/raw/<year>/<month>/` is the authoritative fact; issue bodies are transport, never state. The workflow publishes successful per-result receipts only after accepted facts reach the canonical repository, and an identical retry of an already retained result receives the same successful outcome.
 

@@ -68,13 +68,13 @@ Feature: rumble-client — Local ranked and practice battle client
     Then it creates labelled result issues containing between one and sixty results as required by the result-data contract and correlates each post-publication ingestion receipt to its journal records
     And it neither requests nor uses permission to modify repository contents, branches, releases, packages, Pages, facts, or projections
 
-  @RCL-008 @draft
-  Scenario: The client runtime can execute every supported bot platform within its declared boundary
+  @RCL-008 @retired
+  Scenario: Retired — the client runtime can execute every supported bot platform within its declared boundary
     Test-type: E2E
-    Given the pinned Rumble engine and catalog contain Java, .NET, Python, and TypeScript bots
-    When a contributor builds the primary container or follows a supported bare-metal setup
-    Then the client can boot each platform with the pinned runtime versions and run a battle through Battle Runner
-    And the container restricts bot networking to the local server while client egress is limited to repository synchronization and result submission
+    Given criterion RCL-008 coupled runtime portability and an ambiguous all-in-one container boundary
+    When CH-012 separates supported distribution from phase isolation
+    Then RCL-010 supersedes its runtime portability promise
+    And RCL-011 owns the Docker phase-isolation promise
 
   @RCL-009 @draft
   Scenario: A ranked result reaches the immutable Rumble facts without manual handling
@@ -83,4 +83,21 @@ Feature: rumble-client — Local ranked and practice battle client
     When the client synchronizes, selects and completes a battle, journals its result, and submits it through issue-ops
     Then the result-data ingestion workflow accepts the record as an immutable raw fact and regenerates the affected projections
     And no person copies, edits, or grants repository-content write access to deliver the result
+
+  @RCL-010 @draft
+  Scenario: Native and Docker distributions execute every supported bot platform
+    Test-type: E2E
+    Given a released Rumble engine and catalog contain Java, .NET, Python, and TypeScript bots
+    When a contributor uses the supported native distribution or the recommended Docker image
+    Then both distributions validate the pinned runtime versions and run each platform through Battle Runner
+    And native preflight reports missing prerequisites without installing or changing them
+
+  @RCL-011 @draft
+  Scenario: Docker execution keeps bot code offline and submission credentials out of battles
+    Test-type: Integration
+    Given the Docker launcher uses one bounded client work directory for synchronization, battle, and submission
+    When it runs a ranked session
+    Then synchronization runs online without a submission credential and without starting bot code
+    And battle execution runs without external network access or a submission credential
+    And submission runs online with the Issues-only credential without starting bot code
 ```
@@ -40,7 +40,9 @@ Fork-pull-request submission remains a portability option only after the result-
 
 ## Runtime boundary
 
-The primary distribution is a rebuildable container containing the pinned Tank Royale engine, Battle Runner, and the Java, .NET, Python, and Node.js runtimes required by the catalog. Client network egress is limited to repository synchronization and issue submission; bot processes receive only the local server connection. Documented bare-metal setup remains available with an explicit warning that it does not provide the container boundary.
+Direct host execution and a rebuildable Docker image both run the same client phases and contracts. Docker is the recommended installation because the image contains the pinned Tank Royale engine, Battle Runner, and the Java, .NET, Python, and Node.js runtimes required by the catalog. The native distribution checks those prerequisites but does not install them and warns that direct bot execution has no Docker isolation.
+
+The Docker launcher invokes the image as separate synchronization, battle, and submission processes over one bounded local work directory. Synchronization has network access but no submission credential and starts no bot code. Battle execution has no external network access or submission credential. Submission receives the Issues-only credential but starts no bot code. The image is published only from a release carrying a Tank Royale version with the M-005 contracts, and `engine.json.clientImage` identifies the accepted immutable image digest.
 
 ## External evidence
 

@@ -20,11 +20,11 @@ The client exposes mutually exclusive ranked and practice modes. Ranked mode exe
 
 The append-only local journal is the durability boundary and issue-ops is the only V1 submission transport. The client removes records only after durable ingestion acknowledgement as defined by [ADR-0044](0044-durable-rumble-result-acknowledgement.md). A client credential is limited to Issues access on the result-data repository and never grants repository-content, branch, release, package, Pages, fact, or projection write access. Fork-pull-request submission is introduced only if the result-data contract later supports it.
 
-Replay evidence remains local, bound to its result by battle ID and SHA-256 hash. The primary runtime is a rebuildable, egress-constrained container; bare-metal execution is an explicit fallback with a weaker isolation boundary.
+Replay evidence remains local, bound to its result by battle ID and SHA-256 hash. Direct host execution and a rebuildable Docker image are both supported. Docker is the recommended distribution because it supplies the complete pinned runtime and gives battle execution a narrower host boundary. Its launcher separates synchronization, battle, and submission: synchronization runs online without a submission credential, battle execution runs without external networking or a submission credential, and submission runs online without starting bot code. Direct execution uses the same phases and contracts but has a weaker isolation boundary.
 
 ## Rationale
 
-Separating private experimentation from automatic ranked journaling removes selective submission from the normal workflow. Durable acknowledgement preserves results across publication and receipt-delivery failures. Issue-only credentials limit compromise impact, while local replay evidence supports moderation without making the shared data repository a binary store. The container provides one reproducible multi-runtime execution boundary without requiring central infrastructure.
+Separating private experimentation from automatic ranked journaling removes selective submission from the normal workflow. Durable acknowledgement preserves results across publication and receipt-delivery failures. Issue-only credentials limit compromise impact, while local replay evidence supports moderation without making the shared data repository a binary store. The Docker distribution provides one reproducible multi-runtime environment without requiring central infrastructure, and phase separation keeps credentials out of bot execution.
 
 ## Consequences
 
@@ -33,7 +33,8 @@ Separating private experimentation from automatic ranked journaling removes sele
 - Temporary forge or network failures retain unsent results locally.
 - Moderators may request replay evidence, but the Rumble cannot recover evidence a contributor loses.
 - V1 depends on the forge's issue API; transport portability is deferred until the receiving capability implements it.
-- Bare-metal users accept the residual risk of running reviewed bot source outside the container boundary.
+- Direct-execution users accept the residual risk of running reviewed bot source without Docker isolation.
+- Docker is a contributor-side runtime option, not hosted Rumble infrastructure.
 
 ## References
 

@@ -137,15 +137,15 @@ proposals:
 | **Practice mode** in the client: free local battles against rumble bots, never submitted; ranked mode auto-submits everything. | Client doc |
 | **Replays stay client-side** as read-only evidence, bound to results by `battleId` (UUID) + SHA-256. | Client doc |
 | **Batched submissions** from a local journal; clients never touch Git history (no commits, no amends). | Client doc |
-| **Runtimes ship in the client container** (JVM, .NET, Python, Node.js + pinned engine), tagged by engine version; install scripts as bare-metal fallback. | Client doc |
+| **Native and Docker client distributions are supported**; Docker is recommended and ships the JVM, .NET, Python, Node.js, and pinned engine, while native preflight checks user-installed prerequisites. | Client doc |
 | **Forge ToS reviewed**: this usage is a software project, not detached storage; design keeps traffic and repo size deliberately modest. | Aggregation doc |
 | **Bot names are bound to their owner** at first merge; only the owner's registered accounts may submit new versions. Owners may register multiple forge accounts; account changes require a PR from an already-registered account. | Submission doc |
 | **Official Bot APIs required** for ranked bots (Java, C#, Python, TypeScript); custom frameworks are not eligible. Resolves the dependency allowlist per platform. | Submission doc |
 | **Run from source, never call a compiler**: runtimes compile behind the scenes on clients, and CI validates with a source-run smoke boot instead of a build step. | Submission doc |
 | **Bot slots are configurable**, defaulting to 5 active bot entries per owner for launch. The value must be a named validation/governance constant, not a magic number. | Submission doc |
 | **License required per bot**, validated in CI against a small permissive allowlist; missing or wrong license dismisses the PR. | Submission doc |
 | **Evidence backups are the user's responsibility**, actively encouraged by the client; replays are never held centrally. | Client doc |
-| **Submission at battle boundaries** (a battle = the game type's full round count); container gets a forge-only egress allowlist; journal staleness is bounded by the engine pin. | Client doc |
+| **Submission at battle boundaries** (a battle = the game type's full round count); Docker separates online synchronization and submission from offline credential-free battle execution; journal staleness is bounded by the engine pin. | Client doc |
 | **Issue-ops spelled out**: submissions are labeled forge issues carrying a JSON batch envelope, drained and closed by CI; spam is handled by strict format, per-account budgets, and forge-level blocking as last resort. | Aggregation doc |
 | **Onboarding PR required from day one** for result submitters: a one-time, moderated registration under `clients/` in the data repo; unregistered submissions are closed unprocessed. | Aggregation doc |
 | **GitHub Pages confirmed** for the dashboard; compaction policy settled (monthly rollups to the archive branch after three full months). | Aggregation doc |

@@ -317,9 +317,7 @@ Without central sandbox infrastructure, review cannot make untrusted code safe;
 - The source-tree hash in `index.json` guarantees that what clients run is exactly what was
   reviewed (clients run the sources from the pinned commit, so the hash covers precisely what
   executes).
-- Actual containment happens on the client via the recommended sandbox container, described in the
-  [client document](./client-battles-and-results.md#sandboxing). This split of responsibility
-  (review reduces malice, the container contains it) should be stated plainly in contributor docs.
+- Host containment is available through the recommended Docker distribution described in the [client document](./client-battles-and-results.md#runtimes-native-and-docker-distributions). Its battle phase runs offline without submission credentials; supported native execution knowingly runs reviewed bot code with the contributor's permissions. This split of responsibility should be stated plainly in contributor docs.
 
 ## Licensing