feat(battle-node): reveal choice/Discover tokens to opponent

Choice/Discover-into-hand fanfares add a candidates-only token to hand; the
chosen cardId rides keyAction.selectCard on the generating play, not the
orderList add op. Record idx->chosenCardId at generation (candidate-membership
join) so the later play reveals the real identity via the existing
BuildPlayedCard path; forward {type,cardId} to the opponent and strip
selectCard for hidden (open:0) picks (pass through for open:1, provisional).

- KnownListBuilder.MineChoicePicks + StripKeyActionForOpponent (pure)
- BattleSessionState.RecordChoicePicksFrom (reuses IdxToCardId, no new state)
- PlayActionsBroadcastBody.keyAction + KeyActionEntry/SelectCardEntry
- PlayActionsHandler wires both; EchoHandler unchanged (picks ride the send)

Tests (TDD red->green): 8 KnownListBuilder + 2 dispatch + 2 conformance
(shape-locked to tk2_regular L151 generation / L193 reveal). Full suite 976/0.

Spec: docs/superpowers/specs/2026-06-04-battle-node-choice-token-reveal-design.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs

@@ -56,4 +56,15 @@ internal sealed class BattleSessionState
         foreach (var (idx, cardId, isSelf) in KnownListBuilder.MineAddOps(orderList))
             RecordToken(isSelf == 1 ? from : other, idx, cardId);
     }
+
+    /// <summary>Mine + record choice/Discover-token picks (<see cref="KnownListBuilder.MineChoicePicks"/>)
+    /// into the correct side's map, by the same <c>isSelf</c> routing as <see cref="RecordTokensFrom"/>.
+    /// The chosen cardId rides the generating send's <c>keyAction.selectCard</c> (not the orderList add
+    /// op, which carries candidates only); recorded regardless of the choice's <c>open</c> visibility —
+    /// an unplayed idx is never queried, so a stray record is harmless.</summary>
+    public void RecordChoicePicksFrom(IBattleParticipant from, IBattleParticipant other, object? orderList, object? keyAction)
+    {
+        foreach (var (idx, cardId, isSelf) in KnownListBuilder.MineChoicePicks(orderList, keyAction))
+            RecordToken(isSelf == 1 ? from : other, idx, cardId);
+    }
 }

SVSim.BattleNode/Sessions/Dispatch/Handlers/EchoHandler.cs

@@ -16,6 +16,9 @@ internal sealed class EchoHandler : IFrameHandler
         {
             var orderList = (ctx.Env.Body as RawBody)?.Entries.GetValueOrDefault("orderList");
             ctx.State.RecordTokensFrom(ctx.From, ctx.Other, orderList);
+            // No RecordChoicePicksFrom here: choice picks ride keyAction.selectCard on the generating
+            // SEND, not the receiver's Echo (Echo carries orderList only) — the pick is already
+            // recorded by PlayActionsHandler. MineChoicePicks(orderList, null) would yield nothing.
         }
         return Array.Empty<DispatchRoute>();
     }

SVSim.BattleNode/Sessions/Dispatch/Handlers/PlayActionsHandler.cs

@@ -3,11 +3,12 @@ using SVSim.BattleNode.Protocol.Bodies;
 
 namespace SVSim.BattleNode.Sessions.Dispatch.Handlers;
 
-/// <summary>PvP PlayActions translator (vanilla deck-card slice). Synthesizes the opponent-facing
-/// knownList from the sender's idx->cardId map + the orderList move op, renames targetList ->
-/// oppoTargetList, drops orderList, consumes keyAction.
-/// Token plays resolve their cardId from add ops mined on earlier frames; an un-generated token
-/// idx still degrades to {playIdx,type} (no knownList). Bot drop (no rule).</summary>
+/// <summary>PvP PlayActions translator. Synthesizes the opponent-facing knownList from the sender's
+/// idx->cardId map + the orderList move op, renames targetList -> oppoTargetList, drops orderList,
+/// and forwards a stripped keyAction for choice/Discover plays ({type,cardId}; selectCard dropped
+/// for a hidden open:0 pick). Token plays resolve their cardId from add ops (concrete tokens) or
+/// keyAction.selectCard (choice picks) mined on earlier frames; an un-generated token idx still
+/// degrades to {playIdx,type} (no knownList). Bot drop (no rule).</summary>
 internal sealed class PlayActionsHandler : IFrameHandler
 {
     public IReadOnlyList<DispatchRoute> Handle(FrameDispatchContext ctx)
@@ -20,12 +21,17 @@ internal sealed class PlayActionsHandler : IFrameHandler
         var type = (int)KnownListBuilder.AsLong(entries.GetValueOrDefault("type"));
 
         var orderList = entries.GetValueOrDefault("orderList");
+        var keyAction = entries.GetValueOrDefault("keyAction");
 
         // Mine generated-token identities from this frame's add ops into the right side's idx->cardId
         // map (isSelf:1 → sender; isSelf:0 → opponent, a cross-side gift), so a token played in a LATER
         // frame resolves its cardId — by whichever side ends up playing it (bullet-3 audit F1).
         ctx.State.RecordTokensFrom(ctx.From, ctx.Other, orderList);
 
+        // Choice/Discover-into-hand: the chosen cardId rides keyAction.selectCard (the orderList's
+        // choiceAdd carries candidates only). Record idx->chosenCardId now so the later play reveals it.
+        ctx.State.RecordChoicePicksFrom(ctx.From, ctx.Other, orderList, keyAction);
+
         var deckMap = ctx.State.GetOrSeedDeckMap(ctx.From);
         var played = KnownListBuilder.BuildPlayedCard(deckMap, playIdx, orderList);
         var oppoTargets = KnownListBuilder.RenameTargets(entries.GetValueOrDefault("targetList"));
@@ -34,7 +40,10 @@ internal sealed class PlayActionsHandler : IFrameHandler
             PlayIdx: playIdx,
             Type: type,
             KnownList: played is null ? null : new[] { played },
-            OppoTargetList: oppoTargets);
+            OppoTargetList: oppoTargets,
+            // {type,cardId} forwarded so the opponent renders the choice token; selectCard dropped
+            // when open==0 (hidden draw-to-hand pick). Null for a vanilla play (no keyAction).
+            KeyAction: KnownListBuilder.StripKeyActionForOpponent(keyAction));
 
         var frame = ctx.Env with { Body = body };
         return new[] { new DispatchRoute(ctx.Other, frame, false) };

SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs

@@ -75,6 +75,94 @@ internal static class KnownListBuilder
         }
     }
 
+    /// <summary>Mine choice/Discover-token identities: for each <c>isChoice</c> add op (idx, isSelf,
+    /// candidates), resolve its cardId from the keyAction <c>selectCard</c> pick whose cardId is in that
+    /// op's candidate pool. Yields <c>(idx, cardId, isSelf)</c> — same shape as <see cref="MineAddOps"/>,
+    /// routed by the same <see cref="BattleSessionState.RecordTokensFrom"/> rule. The pick is on
+    /// keyAction.selectCard, NOT the add op (RegisterChoiceAdd strips the concrete cardId,
+    /// <c>NetworkBattleSetupCardEvent.cs:531-543</c>); the candidate-membership join handles the single
+    /// case unambiguously (multi-choice: each chosen cardId matches the one choiceAdd whose candidates
+    /// contain it). <c>type</c>/<c>cardId</c>/<c>open</c> on the keyAction are ignored here — <c>open</c>
+    /// only gates the strip (<see cref="StripKeyActionForOpponent"/>), not the recording. An add whose
+    /// candidates contain none of the picks is skipped (defensive — no record, no desync); Echo (no
+    /// keyAction) yields nothing, leaving it mining-only via <see cref="MineAddOps"/>.</summary>
+    public static IEnumerable<(int Idx, long CardId, int IsSelf)> MineChoicePicks(object? orderList, object? keyAction)
+    {
+        if (orderList is not IEnumerable<object?> ops) yield break;
+
+        // Flatten every selectCard.cardId pick across all keyAction entries into a membership set.
+        var picks = new HashSet<long>();
+        if (keyAction is IEnumerable<object?> kaEntries)
+        {
+            foreach (var ka in kaEntries)
+            {
+                if (ka is not IDictionary<string, object?> kaDict) continue;
+                if (!kaDict.TryGetValue("selectCard", out var scRaw) || scRaw is not IDictionary<string, object?> sc) continue;
+                if (!sc.TryGetValue("cardId", out var idsRaw) || idsRaw is not IEnumerable<object?> ids) continue;
+                foreach (var id in ids) picks.Add(AsLong(id));
+            }
+        }
+        if (picks.Count == 0) yield break;
+
+        foreach (var op in ops)
+        {
+            if (op is not IDictionary<string, object?> opDict) continue;
+            if (!opDict.TryGetValue("add", out var addRaw) || addRaw is not IDictionary<string, object?> add) continue;
+            if (!add.ContainsKey("isChoice")) continue;
+            if (!add.TryGetValue("card", out var cardRaw) || cardRaw is not IDictionary<string, object?> card) continue;
+            if (!card.TryGetValue("candidates", out var candRaw) || candRaw is not IEnumerable<object?> candidates) continue;
+
+            // The chosen cardId is the candidate that the active player picked (∈ picks). One per op.
+            long? chosen = null;
+            foreach (var c in candidates)
+            {
+                var cid = AsLong(c);
+                if (picks.Contains(cid)) { chosen = cid; break; }
+            }
+            if (chosen is null) continue; // no pick in this op's pool — skip (no desync, just no record)
+
+            add.TryGetValue("isSelf", out var isSelfRaw);
+            var isSelf = (int)AsLong(isSelfRaw);
+
+            if (!add.TryGetValue("idx", out var idxRaw) || idxRaw is not IEnumerable<object?> idxList) continue;
+            foreach (var i in idxList)
+                yield return ((int)AsLong(i), chosen.Value, isSelf);
+        }
+    }
+
+    /// <summary>Map an inbound keyAction (the active player's send) to the opponent-facing list:
+    /// for each Choice(1)/HaveBeforeSkillChoice(5) entry, keep <c>{type,cardId}</c> and drop
+    /// <c>selectCard</c> when its <c>open==0</c> (hidden draw-to-hand pick stays secret), pass it
+    /// through when <c>open==1</c> (visible board choice — provisional reveal-immediately, §6).
+    /// Non-choice KeyActionTypes are dropped (current behavior) until their own specs. Returns null
+    /// for absent/empty keyAction or when every entry was dropped (vanilla play unchanged).</summary>
+    public static IReadOnlyList<KeyActionEntry>? StripKeyActionForOpponent(object? keyAction)
+    {
+        if (keyAction is not IEnumerable<object?> entries) return null;
+        var result = new List<KeyActionEntry>();
+        foreach (var e in entries)
+        {
+            if (e is not IDictionary<string, object?> d) continue;
+            d.TryGetValue("type", out var typeRaw);
+            var type = (int)AsLong(typeRaw);
+            if (type is not (1 or 5)) continue; // only Choice / HaveBeforeSkillChoice handled
+
+            d.TryGetValue("cardId", out var cardIdRaw);
+            var cardId = AsLong(cardIdRaw);
+
+            SelectCardEntry? selectCard = null;
+            if (d.TryGetValue("selectCard", out var scRaw) && scRaw is IDictionary<string, object?> sc)
+            {
+                sc.TryGetValue("open", out var openRaw);
+                var open = (int)AsLong(openRaw);
+                if (open != 0 && sc.TryGetValue("cardId", out var idsRaw) && idsRaw is IEnumerable<object?> ids)
+                    selectCard = new SelectCardEntry(ids.Select(AsLong).ToList(), open);
+            }
+            result.Add(new KeyActionEntry(type, cardId, selectCard));
+        }
+        return result.Count == 0 ? null : result;
+    }
+
     /// <summary>Rename <c>targetList</c> -> <c>oppoTargetList</c>; <c>isSelf</c> is actor-relative
     /// and passes through unchanged (F2). Null for a missing/empty list.</summary>
     public static IReadOnlyList<OppoTargetEntry>? RenameTargets(object? targetList)