From ae7ff25af0688d53f1a73a9b31601f4351e7101e Mon Sep 17 00:00:00 2001
From: gamer147 <gamer147@gmail.com>
Date: Mon, 1 Jun 2026 19:53:31 -0400
Subject: [PATCH] feat(battle-node): add BattleType, BattleFinishReason,
 BattlePlayer

Phase 1 foundation types for the v2 broker architecture. Nothing uses
them yet; they land alongside the existing v1.2 code so subsequent
tasks can extract the participant interface and impls.
---
 SVSim.BattleNode/Bridge/BattlePlayer.cs       |  5 +++++
 .../Sessions/BattleFinishReason.cs            | 13 +++++++++++
 SVSim.BattleNode/Sessions/BattleType.cs       | 22 +++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 SVSim.BattleNode/Bridge/BattlePlayer.cs
 create mode 100644 SVSim.BattleNode/Sessions/BattleFinishReason.cs
 create mode 100644 SVSim.BattleNode/Sessions/BattleType.cs

diff --git a/SVSim.BattleNode/Bridge/BattlePlayer.cs b/SVSim.BattleNode/Bridge/BattlePlayer.cs
new file mode 100644
index 0000000..aadb460
--- /dev/null
+++ b/SVSim.BattleNode/Bridge/BattlePlayer.cs
@@ -0,0 +1,5 @@
+namespace SVSim.BattleNode.Bridge;
+
+/// <summary>One player slot for a pending battle. Carries the viewer's identity and
+/// the per-battle MatchContext snapshot built at do_matching time.</summary>
+public sealed record BattlePlayer(long ViewerId, MatchContext Context);
diff --git a/SVSim.BattleNode/Sessions/BattleFinishReason.cs b/SVSim.BattleNode/Sessions/BattleFinishReason.cs
new file mode 100644
index 0000000..f65d639
--- /dev/null
+++ b/SVSim.BattleNode/Sessions/BattleFinishReason.cs
@@ -0,0 +1,13 @@
+namespace SVSim.BattleNode.Sessions;
+
+/// <summary>Reason a participant was terminated. Carried to
+/// <see cref="IBattleParticipant.TerminateAsync"/> so impls can log/clean differently
+/// per cause. Cleanup itself is the same regardless of reason.</summary>
+public enum BattleFinishReason
+{
+    NormalFinish,
+    Retire,
+    OpponentDisconnect,
+    Timeout,
+    ServerAbort,
+}
diff --git a/SVSim.BattleNode/Sessions/BattleType.cs b/SVSim.BattleNode/Sessions/BattleType.cs
new file mode 100644
index 0000000..2a4e5fb
--- /dev/null
+++ b/SVSim.BattleNode/Sessions/BattleType.cs
@@ -0,0 +1,22 @@
+namespace SVSim.BattleNode.Sessions;
+
+/// <summary>
+/// Discriminator for a pending battle and the session it produces. See
+/// docs/superpowers/specs/2026-06-01-battle-node-v2-architecture-design.md.
+/// </summary>
+public enum BattleType
+{
+    /// <summary>Two real players. Server brokers between two WebSockets.
+    /// Both <c>BattlePlayer</c> slots required.</summary>
+    Pvp,
+
+    /// <summary>One real player; opponent runs in the client (prod's IsAINetwork
+    /// path; matched only in rank rotation / rank unlimited per prod). Server is
+    /// ack-only. <c>p2</c> must be null.</summary>
+    Bot,
+
+    /// <summary>One real player; server scripts the opponent (today's v1.2
+    /// behaviour, preserved as a solo testing harness). <c>p2</c> currently null;
+    /// future server-driven bot config can ride on <c>p2</c>.</summary>
+    Scripted,
+}