Merge pull request #8 from robocode-dev/ch-003-own-death-reaches-on-death

Establish why a robot's own death never reaches onDeath

Author: flemming-n-larsen

.clue/id-ledger.yaml

@@ -1,21 +1,21 @@
 counters:
     ADR: "1"
-    AN: "7"
+    AN: "9"
     API: "6"
     ARCH: "3"
     C: "7"
     CAP: "8"
-    CH: "2"
+    CH: "3"
     CRIT: "8"
     DES: "8"
-    G: "1"
+    G: "2"
     IDR: "2"
     OQ: "2"
     P: "1"
     PDR: "1"
     REH: "1"
     ROUTE: "12"
-    TASKS: "2"
+    TASKS: "3"
 entries:
     - id: ADR-001
       kind: numeric
@@ -57,6 +57,16 @@ entries:
       state: live
       prefix: AN
       component: "7"
+    - id: AN-008
+      kind: numeric
+      state: live
+      prefix: AN
+      component: "8"
+    - id: AN-009
+      kind: numeric
+      state: live
+      prefix: AN
+      component: "9"
     - id: API-001
       kind: numeric
       state: live
@@ -187,6 +197,11 @@ entries:
       state: live
       prefix: CH
       component: "2"
+    - id: CH-003
+      kind: numeric
+      state: live
+      prefix: CH
+      component: "3"
     - id: CRIT-001
       kind: numeric
       state: live
@@ -272,6 +287,11 @@ entries:
       state: live
       prefix: G
       component: "1"
+    - id: G-002
+      kind: numeric
+      state: live
+      prefix: G
+      component: "2"
     - id: IDR-001
       kind: numeric
       state: live
@@ -377,3 +397,8 @@ entries:
       state: live
       prefix: TASKS
       component: "2"
+    - id: TASKS-003
+      kind: numeric
+      state: live
+      prefix: TASKS
+      component: "3"

compat-test/README.md

@@ -224,3 +224,10 @@ therefore safe to run over a state file holding results from several eras.
   chunk it; checkpointing makes chunking free.
 - Per-side timeout (`--timeout`, default 600 s) kills the entire worker process tree
   (server/booter/bot JVMs included) and records the robot as failed.
+- **Comparing two Tank Royale server builds**: the runner jar carries an embedded server
+  jar, and rebuilding it does not reliably pick up a change to the server's sources —
+  Gradle's up-to-date check reused a stale shrunk server jar and produced byte-identical
+  runner jars for two different source trees, which silently made a whole comparison
+  meaningless. Clean the modules first (`gradlew :server:clean :runner:clean`) and check
+  the runner jar's checksum between builds; if the checksum did not change, neither did
+  the server.

conformance-test/src/test/java/dev/robocode/tankroyale/bridge/conformance/RoundOutcomeEventsConformanceTest.java

@@ -19,18 +19,24 @@
  * routed through the Bot API's event queue, the bridge dispatched them from a hand-written
  * switch that had no case for the robot's own death, so {@code onDeath} was never called for
  * any robot. A manual switch fails silently on the branch nobody wrote, and nothing in a
- * score report shows it.
+ * score report shows it. Routing through the queue did not fix it either, and AN-009 now has
+ * the reason: the death never reaches the bot, so there is nothing for any dispatcher to route.
+ *
+ * Every passing test in this class is tagged for a criterion it does not prove -- the win-handler
+ * test and both round-completion tests assert behaviour no criterion in CAP-001 covers. G-002
+ * carries that; do not read a passing test here as evidence for the criterion in its name.
  */
 class RoundOutcomeEventsConformanceTest extends ConformanceTestBase {
 
     private static final String ROBOT = "tested.robots.BattleWin";
 
     @Test
-    @Disabled("Fails against the bridge: onDeath is never called. Confirmed and recorded in "
-            + "AN-006, which has the measured marker counts for both engines. Kept rather than "
-            + "deleted because it is the only thing that detects the defect, and disabled rather "
-            + "than left failing so the build stays honest. Re-enable in M-001, which owns the "
-            + "root cause in the Bot API's event queue.")
+    @Disabled("Fails against the bridge: onDeath is never called, because no death event reaches "
+            + "any bot at all. AN-009 has the cause -- the Tank Royale server emits a death before "
+            + "the turn's bot snapshot exists, so it fans out over nobody -- and the repair is "
+            + "committed upstream and unreleased. Kept rather than deleted because it is the only "
+            + "thing that detects the defect, and disabled rather than left failing so the build "
+            + "stays honest. Re-enable when a Tank Royale release carries the repair.")
     @DisplayName("EVT-004: a robot's own death reaches onDeath on both engines")
     void testEVT004_IntegrationPositive_OwnDeathReachesTheDeathHandler() {
         assertOnBothEngines(ROBOT, (outcome, engine) ->

docs/analysis/AN-008-tank-royale-declares-more-round-winners-than-rounds.md

@@ -0,0 +1,45 @@
+---
+id: AN-008
+type: analysis
+status: active
+links: [CAP-001, AN-006, AN-009, PDR-001]
+title: Tank Royale declares more round winners than the battle has rounds
+provenance: inferred
+reversal-cost: low
+---
+
+# AN-008 — Tank Royale declares more round winners than the battle has rounds
+
+## What was investigated
+
+Round outcomes, noticed while measuring [`AN-009`](AN-009-the-server-never-sends-a-death-to-any-bot.md). Classic's `BattleWin` robot prints a marker from `onWin` and from `onDeath`, so a battle's win and death totals can be counted from the two robot consoles. Once deaths began arriving under the bridge, the win totals became readable against them for the first time.
+
+## What was found
+
+A robot can win a round only once, so the wins in a battle can never exceed its rounds. Classic obeys that. Tank Royale does not.
+
+Measured over five-round battles of `BattleWin` against a copy of itself, at the roborumble division, on 2026-08-30:
+
+| Engine | Wins per battle | Deaths per battle |
+|---|---|---|
+| Classic Robocode | 5, 5, 5, 5, 5, 4, 5, 5, 4 | 5, 7, 6, 5, 5, 6, 6, 6, 6 |
+| Tank Royale, current server | 5, 5, 5, 6, 7, 7 | none delivered — `AN-009` |
+| Tank Royale, server with the `AN-009` repair | 4, 4, 5, 5, 6, 7 | equal to the wins, in every battle |
+
+Classic never exceeded its round count. Tank Royale reached seven wins in a five-round battle, on both the repaired and the unrepaired server, so this is independent of the death defect and is not caused by its repair.
+
+The likely shape: a round that ends in mutual destruction. Classic's deaths exceed its wins, which is what a mutual kill looks like when one robot is still declared the winner. Under the bridge the two totals are equal in every battle measured, which is what it looks like when both are declared winners.
+
+## Why it was invisible until now
+
+There was nothing to read the win totals against. With no deaths arriving, a battle's markers were wins and round ends only, and a win total of six in a five-round battle is not obviously wrong unless you are already counting. `AN-009`'s defect hid this one.
+
+## What this does not establish
+
+The cause. Nothing in the server has been traced; the shape above is inferred from the totals and from how classic's totals differ, not demonstrated. Whether the extra winner also receives the round's score, and therefore whether this moves rumble results, is unmeasured — and that is the question that decides how much it matters.
+
+It is also not established which engine is right about the scoring rule, only that they differ. Classic is the specification, so classic is right by definition about what a robot observes; whether Tank Royale intends a different rule for its own bots is a question for that project.
+
+## Where it goes
+
+No criterion in `CAP-001` covers how many robots may be declared the winner of a round, so nothing currently fails because of this. Nor does any criterion cover round and battle completion reaching their handlers — the tests that assert it are tagged for criteria that say something else, which is what [`G-002`](../goals/G-002-conformance-evidence-proves-the-criterion-it-names.md) exists to repair. A criterion for the winner count belongs to `CAP-001` and needs the cause established first, because a criterion written against inferred behaviour would encode the guess.

docs/analysis/AN-009-the-server-never-sends-a-death-to-any-bot.md

@@ -0,0 +1,68 @@
+---
+id: AN-009
+type: analysis
+status: active
+links: [CAP-001, AN-006, AN-008, PDR-001, C-006]
+title: The Tank Royale server never sends a death event to any bot, which is why onDeath never fires
+provenance: inferred
+reversal-cost: low
+---
+
+# AN-009 — The Tank Royale server never sends a death event to any bot
+
+## What was investigated
+
+The cause of [`AN-006`](AN-006-own-death-still-does-not-reach-on-death.md), which measured that `onDeath` is never called under the bridge and named a suspect it could not confirm: the Bot API event queue's age and criticality filter. This spike set out to establish which of three things is true — the death event never reaches the queue, it reaches the queue and is discarded, or it is dispatched onto a thread that has already stopped.
+
+None of the three. The question was wrong, because it assumed a death event arrives at the bot at all.
+
+## What was found
+
+**No death message of any kind reaches any bot.** Not the dying bot, not the survivors.
+
+A probe in the Bot API's `WebSocketHandler.onText`, ahead of any parsing, printed the raw payload of every message whose text contained `death` in any casing. Across a two-participant battle and a four-participant battle, five rounds each, it fired zero times in every bot's log. The same logs show scan, wall-hit, bullet-hit, bullet-hit-bot and won-round events arriving and dispatching normally.
+
+The four-participant run is the one that settles it. Three bots die there while the round continues, so the survivors should be told about each death. They were not.
+
+The cause is in the Tank Royale server, in `TurnProcessor.processTurn`. A death is emitted with `addPublicBotEvent`, which fans out over the turn's own bots. Every turn is constructed empty and only filled from the bots map at the end of that pipeline, and the emission ran before that snapshot, so the event was delivered to nobody. The server's own turn-pipeline unit test reproduces it with no engine, no network, and no bot processes: a defeated bot yields an empty event map.
+
+## What was ruled out, and how
+
+**The Bot API's event queue** — the suspect `AN-006` named. Refuted twice. By reading: `DeathEvent.isCritical()` returns true, and the queue exempts critical events from its age filter. By measurement: a probe printed the queue's full contents at every dispatch and no death event was ever in it. Nothing was dropped, because nothing arrived.
+
+**A negative priority.** Ruled out by reading rather than by probe: the bridge registers `DeathEvent` at priority -1, matching classic, and the queue does not filter on priority sign.
+
+**The Bot API's instant death handler.** `BotInternals` subscribes a handler to `DeathEvent` whose body stops the bot thread, and the bridge's bot inherits it, so it could in principle stop the thread before the queued dispatch ran. This was the hypothesis the change was opened on. A probe on that handler never fired.
+
+**The bridge.** It overrides the Bot API's `onDeath`, maps it, and calls the robot's handler. A probe inside that override never fires, because it is never called. The bridge needs no change.
+
+## The repair
+
+Emitting after the turn's snapshot, which still holds the dead bots, so a bot also receives its own death. Committed in the Tank Royale repository (`https://github.com/robocode-dev/tank-royale`) on the local branch `fix-death-events-never-reach-bots`, with a positive and a negative test in the server's own turn-pipeline suite; the positive test fails without the change and the server suite passes with it. At the time of writing that branch is not pushed and has no pull request, so nothing downstream can consume it yet.
+
+`C-006` does not apply. The obligation to land a change in all four language implementations is about the Bot API; this is server code, and the server exists once.
+
+## The controlled comparison
+
+Every Tank Royale build was rebuilt from clean and identified by the runner jar's checksum. The first attempt at this comparison was worthless: Gradle's up-to-date check reused a stale shrunk server jar and produced byte-identical runner jars for two different source trees. Six five-round battles per build, against nine classic battles, on 2026-08-30:
+
+| Build | wins per battle | deaths per battle |
+|---|---|---|
+| The runner jar the bridge builds against | 4, 5, 5 | 0 in every battle |
+| Current Tank Royale `main` | 5, 5, 5, 6, 7, 7 | 0 in every battle |
+| Current `main` with the repair | 4, 4, 5, 5, 6, 7 | equal to the wins, in every battle |
+| Classic Robocode | 5, 5, 5, 5, 5, 4, 5, 5, 4 | 5, 7, 6, 5, 5, 6, 6, 6, 6 |
+
+Deaths appear only with the repair. Wins are untouched by it — totals above five occur on the unrepaired build too, which is [`AN-008`](AN-008-tank-royale-declares-more-round-winners-than-rounds.md) and not this.
+
+## What supersedes AN-006
+
+`AN-006`'s conclusions, not its measurement. Its marker table stands as what was observed then; its suspect is refuted above.
+
+Its recorded second divergence — classic splitting the rounds 3–2 between the instances while the bridge gave one instance all five — did not reproduce. Wins split across the instances in every battle measured here. It was recorded before the event-dispatch redesign and the Bot API upgrade, and nothing here re-establishes it.
+
+## What this means for the criteria
+
+`EVT-004` stays `@draft`. The behaviour is missing, the cause is established, and the repair is unreleased; the bridge builds against released Bot API and runner artifacts rather than local ones, so nothing here can promote it. The reason is now a named cause with a named fix rather than an absence.
+
+`EVT-007` — the death of another robot reaches the survivors — is blocked by the same cause, which nobody had written down. It was recorded as merely unported. Any classic robot that tracks enemies through `onRobotDeath` is running blind under the bridge, which is a wider fidelity gap than one handler on one robot.

docs/analysis/README.md

@@ -15,4 +15,6 @@ An incident where the corpus was green but later evidence contradicted it carrie
 - [AN-006 — A robot's own death still does not reach onDeath under the bridge](AN-006-own-death-still-does-not-reach-on-death.md) · `active` — Whether `EVT-004` holds: a robot's own death reaches its death handler.
 - [AN-004-extraction/](AN-004-extraction/README.md)
 - [AN-007 — Remaining turn had opposite signs depending on which path a robot read it through](AN-007-remaining-turn-sign-disagreed-between-two-paths.md) · `active` — Two conversion paths for one quantity disagreed, and the test written alongside AN-005 had certified the wrong one.
+- [AN-008 — Tank Royale declares more round winners than the battle has rounds](AN-008-tank-royale-declares-more-round-winners-than-rounds.md) · `active` — Round outcomes, noticed while measuring `AN-006`.
+- [AN-009 — The Tank Royale server never sends a death event to any bot, which is why onDeath never fires](AN-009-the-server-never-sends-a-death-to-any-bot.md) · `active` — The cause of `AN-006`, which measured that `onDeath` is never called under the bridge and named a suspect it could not confirm: the Bot API event queue's age and criticality filter.
 <!-- clue:index:end -->

docs/capabilities/CAP-001-event-dispatch-parity/README.md

@@ -34,3 +34,5 @@ The physics the events describe. That a `ScannedRobotEvent` arrives at the right
 ## Status
 
 `draft`. The redesign that routed events through the Bot API's own event queue is implemented and believed correct, but it was verified by running battles and reading scores. Every criterion here is unproven in the sense that matters: nothing would tell us if it broke again. `M-001` is the plan door.
+
+The conformance tier now reaches some of them, and the capability still holds at `draft` for two separate reasons. `EVT-004` and `EVT-007` have an established cause and an unreleased repair — [`AN-009`](../../analysis/AN-009-the-server-never-sends-a-death-to-any-bot.md): the Tank Royale server sends no death to any bot, so neither the dying robot nor the survivors are told. And the tests that do pass here are not all tagged for what they prove; [`G-002`](../../goals/G-002-conformance-evidence-proves-the-criterion-it-names.md) carries that, and until it is repaired a passing test in this capability is not on its own grounds for promoting the criterion it names.

docs/capabilities/CAP-001-event-dispatch-parity/criteria.md

@@ -38,22 +38,31 @@ Feature: Event dispatch and timing parity
     Given a robot that turns its radar from inside onHitWall and marks when it is scanned
     When the same battle runs on both engines
     Then the robot reports being scanned on both engines
-    # Proven by the ported InteruptibleEvent robot. Plan door: M-001.
+    # The ported InteruptibleEvent robot is tested in InterruptibleEventConformanceTest and passes,
+    # but it does not prove this scenario's name: the robot sets HitWallEvent to the SAME priority as
+    # ScannedRobotEvent, so nothing higher-priority arrives, and the assertion cannot separate
+    # re-entry from an ordinary later delivery. Promotion was attempted in CH-003 and reverted.
+    # This is the same defect as the EVT-005 mistag; see G-002. Plan door: M-001.
 
   @EVT-004 @draft
   Scenario: A robot's own death reaches its death handler
     Test-type: Integration
     Given a robot that reports from onDeath
     When the robot is destroyed on each engine
     Then the report appears on both engines
-    # This dispatched nowhere at all before the redesign: no death case existed. Plan door: M-001.
+    # Draft because the behaviour is missing, not because nothing tests it: the test exists and
+    # is disabled. AN-009 establishes the cause -- the Tank Royale server emits a death before the
+    # turn's bot snapshot exists, so it reaches no bot at all -- and the repair is committed
+    # upstream and unreleased. Promote when a release carries it. Plan door: M-001.
 
   @EVT-005 @draft
   Scenario: New-turn events arrive at the classic point in the turn
     Test-type: Integration
     Given a robot that records the turn number at each handler entry
     When the same battle runs on both engines
     Then each handler is entered at the same point in the turn on both engines
+    # Draft, and not proven by the tests currently tagged EVT-005: those assert round and battle
+    # completion, which is different behaviour and which no criterion here covers. See G-002.
     # Plan door: M-001.
 
   @EVT-006 @draft
@@ -70,7 +79,8 @@ Feature: Event dispatch and timing parity
     Given a robot that reports each robot death it observes
     When the same battle runs on both engines
     Then the same deaths are reported in the same order on both engines
-    # Proven by the ported RobotDeathEvents robot. Plan door: M-001.
+    # Proven by the ported RobotDeathEvents robot. Blocked by the same cause as EVT-004: no death
+    # event reaches any bot, so the survivors are not told either. See AN-009. Plan door: M-001.
 
   @EVT-008 @draft
   Scenario: Skipped turns are reported to the robot