SVSimServer/SVSim.BattleNode/README.md

# SVSim.BattleNode

Socket.IO node-server scaffolding for in-battle traffic. Implements the second of the prod 4-server topology — the realtime channel that handles `Matched` / `BattleStart` / `Deal` / per-action `PlayActions` / `Echo` / `TurnEnd` between the client and a server-side opponent.

**v1 scope** is "scripted thin sequencer": the server accepts a connection, walks a hand-rolled lifecycle from `InitNetwork` to mulligan + first turn + opponent TurnStart, then sits at the opponent's-turn screen indefinitely. No real opponent, no `battleCode` validation, no recovery. v2 work targets each of those.

The library has **no dependency on `SVSim.EmulatedEntrypoint`**. It exposes one DI seam (`IMatchingBridge`) and one ASP.NET Core integration surface (`AddBattleNode` / `UseBattleNode`). Pulling the node into a separate process later is one interface and one Kestrel binding.

## Architecture

```
SVSim.BattleNode/
├─ Bridge/          IMatchingBridge — what /do_matching calls to mint a battle id + node URL
├─ Hosting/         ASP.NET Core extensions + the /socket.io/ endpoint handler
├─ Lifecycle/       ScriptedLifecycle — the v1 hand-rolled Matched/BattleStart/Deal/Swap/Ready frames
├─ Protocol/        MsgEnvelope, NetworkBattleUri enum, msgpack ↔ envelope codec
├─ Reliability/     InboundTracker (pubSeq dedup), OutboundSequencer (playSeq archive), Gungnir
├─ Sessions/        BattleSession (per-connection state + WS pump), IBattleSessionStore
└─ Wire/            EIO3 framing, SIO2 framing, NodeCrypto (AES-256-CBC)
```

## Connect handshake (verified end-to-end against the real client)

```
┌────────┐                                                    ┌────────────┐
│ Client │                                                    │ BattleNode │
└────┬───┘                                                    └──────┬─────┘
     │                                                                │
     │  HTTP POST /arena_two_pick_battle/do_matching                 │ (HTTP host)
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── { matching_state:3004, battle_id, node_server_url,       │
     │        card_master_id, ... }                                  │
     │                                                                │
     │  WS upgrade  ws://<node>/socket.io/                            │
     │     headers: BattleId, viewerId=encryptForNode(uid)            │
     ├──────────────────────────────────────────────────────────────►│ AcceptWebSocketAsync
     │  ◄── EIO3 Open  0{sid,upgrades:[],pingInterval,pingTimeout}    │
     │                                                                │
     │  msg: InitNetwork  (cat=99/general)                            │
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── synchronize: InitNetwork{resultCode:1}                    │
     │                                                                │
     │  MatchingInitBattle: status=Connect; subscribe receiver        │
     │  msg: InitBattle   (cat=2/matching)                            │
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── synchronize: Matched{selfInfo,oppoInfo,selfDeck,bid}      │
     │                                                                │
     │  client loads decks/scene                                      │
     │  msg: Loaded                                                   │
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── synchronize: BattleStart{turnState,battleType,...}        │
     │  ◄── synchronize: Deal{self,oppo}                              │
     │                                                                │
     │  mulligan UI; player chooses cards to swap                     │
     │  msg: Swap{idxList:[...]}                                      │
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── synchronize: Swap{self:[post-mulligan hand]}              │
     │  ◄── synchronize: Ready{self,oppo,idxChangeSeed,spin}          │
     │                                                                │
     │  turn 1: TurnStart, PlayActions, ..., TurnEnd                  │
     ├──────────────────────────────────────────────────────────────►│
     │  ◄── synchronize: TurnStart{spin}    (opponent turn signal)    │
     │                                                                │
     │  sits at "Opponent's turn…" — v1 stopping point                │
```

Each push from us carries a contiguous `playSeq`; client-emit `pubSeq` is echoed back via the Socket.IO ack callback. `Gungnir` runs a 5s alive heartbeat in parallel reporting `scs:ONLINE,ocs:ONLINE`.

## Wire-format gotchas (discovered during v1 smoke)

These are not in the original protocol docs and tripped us during the smoke walkthrough — leaving them here so the next reader doesn't repeat the diagnosis.

| Spec said | Actual wire | Where it shows up |
|---|---|---|
| `AdditionalQueryParams` on the WS upgrade | **HTTP request headers**, not query string. BestHTTP misnames the API. | `BattleNodeWebSocketHandler.ReadCredential` reads `BattleId` / `viewerId` from headers first, query as fallback (for tests). |
| `node_server_url` ws://host:port | `host:port/socket.io/` — **no scheme prefix**, **path included**. | `BattleNodeOptions.NodeServerUrl` default + `do_matching` response. |
| `card_master_id` optional | **Required** when `matching_state ∈ {3004,3007,3011}` — no `Keys.Contains` guard client-side. | Added to `DoMatchingResponseDto` with default `1`. |
| `resultCode` optional on pushes | **Required = 1** on every scripted synchronize frame; missing means "drop in error handler". | `ScriptedLifecycle.EnvelopeForPush` injects it. |
| Matched in response to InitNetwork | **InitBattle**. Matched in response to InitNetwork lands before the client's matching handler is subscribed and silently drops. | See dispatch in `BattleSession.ComputeResponses`. |
| WS binary frames carry raw msgpack | EIO3 prefixes binary frames with `0x04` (Message type byte), same as the leading digit on text frames. | `BattleSession.RunAsync` strips on read; `EncodeAndSendAsync` prepends on send. |

There's also a JSON parsing pitfall worth knowing about (and that broke the mulligan): the inline conditional `el.TryGetInt64(out var l) ? l : el.GetDouble()` unifies its branches to the common implicit-convertible type. Since `long → double` is implicit, the long silently widens to double, and `OfType<long>` downstream drops every entry. See `MsgEnvelope.ParseNumber` for the fix — keep number parsing in a separate method so each branch boxes its own runtime type.

## v1 scripted opponent — what the client sees

Hardcoded in `ScriptedLifecycle`:

- **Your deck** is 30 copies of `cardId = 100011010` (a neutral card stable across card-master versions). Your actual TK2 draft is ignored.
- **Your leader** is `classId="1"`, `charaId="1"` regardless of class you drafted.
- **Opponent** is a fixed silhouette: `classId="8"`, KOR sleeve/emblem/degree, viewer id `999999999`.
- **Battle seed** is `17548138L` in both info blocks (the seed is *shared* per battle per the spec).
- **Mulligan** does real card replacement: any idx in your `idxList` is swapped for the next unused deck idx (`1..3` dealt, so `4..30` are pool).
- **Opponent's turn** never actually does anything — we push a single `TurnStart{spin:100}` after your `TurnEnd` so the UI transitions to the opponent-turn display, then sit.

## Where to extend

| You want to | Touch |
|---|---|
| Use the real drafted deck | `ScriptedLifecycle.BuildMatched` (`selfDeck`) + the `IMatchingBridge` to plumb the viewer's TK2 run state through |
| Show the real drafted class | `ScriptedLifecycle.BuildBattleStart` (`selfInfo.classId/charaId`) — read from the same source |
| Add a real AI opponent | Replace the static dispatch in `BattleSession.ComputeResponses` (`TurnEnd → opponent TurnStart` case) with one that drives a decision engine. The `OutboundSequencer` already assigns `playSeq` for whatever you push. |
| Implement recovery | `IBattleSessionStore` already keeps the pending registry. Add a per-battle archive (the `OutboundSequencer.Archive` already retains every assigned-playSeq push) and bind it to the HTTP `/battle/get_recovery_params` endpoint. |
| Validate `battleCode` | Port `NetworkConsistency.GetConsistency` from the client decompilation. Hook into `BattleSession.HandleMsgEventAsync` on `TurnEnd` / `Judge`. |
| Type the `orderList` register actions | Spec at `docs/api-spec/in-battle/register-actions.md` catalogs the eight shapes observed in TK2 captures. Build a discriminated union; replace `Dictionary<string, object?>` in the `Body` for the relevant URIs. |

## Test layout

```
SVSim.UnitTests/BattleNode/
├─ Bridge/         MatchingBridgeTests           (3 tests — mint id, dedup, format)
├─ Integration/   BattleNodeFlowTests           (end-to-end via WebApplicationFactory)
│                 RawSocketIoTestClient         (test helper)
├─ Lifecycle/     ScriptedLifecycleTests        (11 tests)
├─ Protocol/      MsgEnvelopeTests              (4 tests incl. number-array regression)
│                 MsgPayloadCodecTests          (2 tests — roundtrip + known vector)
├─ Reliability/   GungnirTests / InboundTrackerTests / OutboundSequencerTests
├─ Sessions/      BattleSessionDispatchTests    (8 tests — phase-state machine)
│                 InMemoryBattleSessionStoreTests
└─ Wire/          NodeCryptoTests (with fixed-vector regression)
                  EngineIoFrameTests
                  SocketIoFrameTests (incl. binary attachment + JSON escaping)
```

Total ~71 BattleNode-scoped tests. The integration test boots the EmulatedEntrypoint host via `SVSimTestFactory`, mints a battle through `IMatchingBridge`, opens a TestServer WebSocket, and walks the full handshake through Ready. It exercises every layer.

## Related docs

- `docs/api-spec/in-battle/transport.md` — Socket.IO + AES-for-node wire format, with smoke corrections inline.
- `docs/api-spec/in-battle/matching.md` — `do_matching` bridge + client state machine.
- `docs/api-spec/in-battle/server-to-client.md`, `client-to-server.md` — per-uri frame shapes.
- `docs/api-spec/in-battle/register-actions.md` — `orderList` action catalog (for v2).
- `docs/api-spec/in-battle/reliability.md` — pubSeq/playSeq stocking + Gungnir.
- `docs/api-spec/in-battle/recovery.md` — the reconnect handshake (deferred to v2).
- `docs/operations/battle-node-smoke.md` — manual end-to-end checklist.
- `docs/operations/battle-node-smoke-walkthrough.md` — annotated walkthrough with per-step diagnostics.
- `docs/superpowers/specs/2026-05-31-battle-node-transport-design.md` — v1 design.
- `docs/superpowers/plans/2026-05-31-battle-node-transport.md` — v1 implementation plan.