Document lifecycle compatibility boundaries

Author: flemming-n-larsen

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

@@ -38,6 +38,8 @@ Since Bot API 1.0.2, new-turn events dispatch at the end of `execute()`, which i
 
 The Bot API's event publisher catches subscriber runtime exceptions so one callback cannot prevent other subscribers from receiving the event. That is compatible with classic's continued battle processing, but it hides the failure from the process logs that form conformance evidence. `BotPeer` therefore reports runtime exceptions at the legacy callback boundary and then returns to the Bot API queue; control-flow errors used by the Bot API for interruptible handlers pass through unchanged. `IDR-006` records this narrow exception-reporting rule.
 
+When a round ends, a callback already running on the old robot thread can overlap the next round's tick cleanup. A state read in that stale callback then raises the Bot API's "tick has not occurred yet" exception after the robot has stopped. `BotPeer` contains only that stopped-bot signature; active-bot and other callback exceptions remain visible.
+
 ## The guard
 
 `setInterruptible` is null-guarded. The Bot API permits the call at points where no event is currently being dispatched, and a robot may reach it through a code path where the current event is absent. The upstream fix landed in the Bot API across its language implementations under `C-006`; the guard here is the local defence.

docs/capabilities/CAP-008-call-routing-fidelity/design.md

@@ -16,6 +16,8 @@ reversal-cost: low
 
 That is the whole enabling change, and it is small on purpose. Routing is only observable at the boundary between the two APIs, and in a battle that boundary sits behind a WebSocket and reports back as a score. With the seam it is a method call and an assertion.
 
+The generated wrapper leaves peer attachment until `GameStarted`. Tank Royale has not populated `GameSetup` when the bot is constructed, while classic robots may read battlefield dimensions from `setPeer()`. Attaching at the callback presents the setup-backed state without changing the frozen `robocode.*` surface.
+
 ## The fake
 
 `RecordingBot` is a dynamic proxy over `IBot` that records every call with its arguments and answers canned values for getters.