test(battle-node): lock token-reveal knownList shape vs prod capture line 96

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

SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs

@@ -4,15 +4,17 @@ namespace SVSim.BattleNode.Sessions.Dispatch;
 
 /// <summary>Mutable per-session state shared across frame handlers. The mulligan barrier's
 /// post-swap hands, plus (PvP-equivalency, vanilla slice) the per-side idx->cardId map used to
-/// synthesize the opponent-facing <c>knownList</c>. FUTURE: a token map (cardIds mined from
+/// synthesize the opponent-facing <c>knownList</c>. Generated tokens (cardIds mined from
-/// orderList <c>add</c> ops, idx>30) + a reveal-gate set land alongside <see cref="IdxToCardId"/>.</summary>
+/// orderList <c>add</c> ops) are recorded into the SAME
+/// <see cref="IdxToCardId"/> map via <see cref="RecordToken"/>; a reveal-gate set is still future.</summary>
 internal sealed class BattleSessionState
 {
     public BattleSessionPhase SessionPhase { get; set; } = BattleSessionPhase.AwaitingInitNetwork;
     public Dictionary<IBattleParticipant, long[]> PostSwapHands { get; } = new();
 
     /// <summary>Per-side idx->cardId, seeded lazily from <see cref="MatchContext.SelfDeckCardIds"/>.
-    /// Deck cards only (idx 1..deckCount); tokens (idx>deckCount) are deferred.</summary>
+    /// Holds deck cards (idx 1..deckCount, seeded) and generated tokens (idx>deckCount, recorded
+    /// from add ops via <see cref="RecordToken"/>).</summary>
     public Dictionary<IBattleParticipant, Dictionary<int, long>> IdxToCardId { get; } = new();
 
     /// <summary>The sender's idx->cardId map, seeding it from its <see cref="MatchContext"/> on first
@@ -28,4 +30,15 @@ internal sealed class BattleSessionState
         }
         return map;
     }
+
+    /// <summary>Record a generated token's identity into the side's idx->cardId map (the same map
+    /// that holds deck cards). Mined from the sender's <c>orderList</c> <c>add</c> ops by
+    /// <see cref="KnownListBuilder.MineAddOps"/>; surfaced later by <c>BuildPlayedCard</c> when the
+    /// token is the played card. Deck idxs (1..deckCount) and token idxs (&gt;deckCount) don't
+    /// collide — the client allocates token idxs after the deck.</summary>
+    public void RecordToken(IBattleParticipant side, int idx, long cardId)
+    {
+        GetOrSeedDeckMap(side);            // ensure the per-side map exists (deck-seeded)
+        IdxToCardId[side][idx] = cardId;   // overwrite-on-conflict: latest identity wins
+    }
 }

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

@@ -5,8 +5,9 @@ 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 (idx>deck) degrade silently to
+/// oppoTargetList, drops orderList, consumes keyAction.
-/// {playIdx,type} (no knownList). Bot drop (no rule).</summary>
+/// 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>
 internal sealed class PlayActionsHandler : IFrameHandler
 {
     public IReadOnlyList<DispatchRoute> Handle(FrameDispatchContext ctx)
@@ -18,8 +19,15 @@ internal sealed class PlayActionsHandler : IFrameHandler
         var playIdx = (int)KnownListBuilder.AsLong(entries.GetValueOrDefault("playIdx"));
         var type = (int)KnownListBuilder.AsLong(entries.GetValueOrDefault("type"));
 
+        var orderList = entries.GetValueOrDefault("orderList");
+
+        // Mine generated-token identities from this frame's add ops into the sender's idx->cardId
+        // map, so a token played in a LATER frame resolves its cardId (bullet-3 audit F1).
+        foreach (var (idx, cardId) in KnownListBuilder.MineAddOps(orderList))
+            ctx.State.RecordToken(ctx.From, idx, cardId);
+
         var deckMap = ctx.State.GetOrSeedDeckMap(ctx.From);
-        var played = KnownListBuilder.BuildPlayedCard(deckMap, playIdx, entries.GetValueOrDefault("orderList"));
+        var played = KnownListBuilder.BuildPlayedCard(deckMap, playIdx, orderList);
         var oppoTargets = KnownListBuilder.RenameTargets(entries.GetValueOrDefault("targetList"));
 
         var body = new PlayActionsBroadcastBody(

SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs

@@ -42,6 +42,37 @@ internal static class KnownListBuilder
         return null;
     }
 
+    /// <summary>Mine generated-token identities from the sender's <c>add</c> ops: yields
+    /// <c>(idx, cardId)</c> for every idx in each <c>{add:{idx:[...], isSelf:1, card:{cardId}}}</c>
+    /// op. Skips <c>isSelf:0</c> adds (cross-side gifts — belong in the other side's map, deferred)
+    /// and any add whose <c>card</c> has no concrete <c>cardId</c> — choice tokens
+    /// (<c>card:{candidates}</c>, <c>RegisterChoiceAdd</c>), copy tokens (<c>card:{baseIdx}</c>,
+    /// <c>RegisterCopyToken</c>), and private-group adds (string <c>idx</c>) — all deferred and all
+    /// caught by the <c>cardId</c>-key / <c>idx</c>-is-list guards. This is the only place a
+    /// freshly-generated card's identity exists on the wire (bullet-3 audit F1; producing code
+    /// <c>RegisterToken</c>/<c>RegisterActionBase</c>) — the played-card op itself never carries a
+    /// <c>cardId</c>.</summary>
+    public static IEnumerable<(int Idx, long CardId)> MineAddOps(object? orderList)
+    {
+        if (orderList is not IEnumerable<object?> ops) 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;
+
+            add.TryGetValue("isSelf", out var isSelfRaw);
+            if (AsLong(isSelfRaw) != 1) continue; // own tokens only; cross-side gifts deferred
+
+            if (!add.TryGetValue("card", out var cardRaw) || cardRaw is not IDictionary<string, object?> card) continue;
+            if (!card.TryGetValue("cardId", out var cardIdRaw)) continue; // candidates/isChoice → no identity yet
+            var cardId = AsLong(cardIdRaw);
+
+            if (!add.TryGetValue("idx", out var idxRaw) || idxRaw is not IEnumerable<object?> idxList) continue;
+            foreach (var i in idxList)
+                yield return ((int)AsLong(i), cardId);
+        }
+    }
+
     /// <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)

SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs

@@ -303,6 +303,55 @@ public class CaptureConformanceTests
         }
         Assert.That(ourEntry.GetProperty("cardId").GetInt64(), Is.EqualTo(128821011L));
     }
+
+    [Test]
+    public void SynthesizedKnownList_for_a_generated_token_matches_prod_recv_shape()
+    {
+        // Prod recv PlayActions for a PLAYED token (battle-traffic_tk2_regular.ndjson:96):
+        // the token's cardId was generated by an earlier add op, not present in any deck.
+        const string prodEntry = """
+        { "idx": 38, "cardId": 900811111, "to": 20, "cost": 1, "clan": 8, "tribe": "0", "spellboost": 0, "attachTarget": "" }
+        """;
+
+        // Compose the two new pure pieces: mine the token from a generating frame's add op,
+        // then build the played-card entry from the resulting map.
+        var generatingOrderList = new List<object?>
+        {
+            new Dictionary<string, object?> { ["add"] = new Dictionary<string, object?>
+                { ["idx"] = new List<object?> { 38L }, ["isSelf"] = 1L,
+                  ["card"] = new Dictionary<string, object?> { ["cardId"] = 900811111L } } },
+        };
+        var map = new Dictionary<int, long>();
+        foreach (var (idx, cardId) in SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.MineAddOps(generatingOrderList))
+            map[idx] = cardId;
+
+        var playOrderList = new List<object?>
+        {
+            new Dictionary<string, object?> { ["move"] = new Dictionary<string, object?>
+                { ["idx"] = new List<object?> { 38L }, ["isSelf"] = 1L, ["from"] = 10L, ["to"] = 20L } },
+        };
+        var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(map, 38, playOrderList);
+        Assert.That(entry, Is.Not.Null, "the mined token resolves to a knownList entry");
+
+        var body = new SVSim.BattleNode.Protocol.Bodies.PlayActionsBroadcastBody(
+            PlayIdx: 38, Type: 30, KnownList: new[] { entry! }, OppoTargetList: null);
+        var env = new MsgEnvelope(NetworkBattleUri.PlayActions, ViewerId: 1, Uuid: "u", Bid: null, Try: 0,
+            Cat: EmitCategory.Battle, PubSeq: null, PlaySeq: null, Body: body);
+
+        using var ourDoc = JsonDocument.Parse(MsgEnvelope.ToJson(env));
+        var ourEntry = ourDoc.RootElement.GetProperty("knownList")[0];
+        using var prodDoc = JsonDocument.Parse(prodEntry);
+
+        // We own idx/cardId/to; cost/clan/tribe are deferred (receiver re-derives from cardId).
+        foreach (var key in new[] { "idx", "cardId", "to" })
+        {
+            Assert.That(ourEntry.TryGetProperty(key, out var ours), Is.True, $"knownList entry missing '{key}'");
+            var prodVal = prodDoc.RootElement.GetProperty(key);
+            Assert.That(ours.ValueKind, Is.EqualTo(prodVal.ValueKind), $"'{key}' type category mismatch");
+        }
+        Assert.That(ourEntry.GetProperty("cardId").GetInt64(), Is.EqualTo(900811111L));
+        Assert.That(ourEntry.GetProperty("to").GetInt32(), Is.EqualTo(20));
+    }
 }
 
 /// <summary>

SVSim.UnitTests/BattleNode/Sessions/BattleSessionDispatchTests.cs

@@ -250,7 +250,7 @@ public class BattleSessionDispatchTests
     }
 
     [Test]
-    public void Pvp_PlayActions_token_idx_degrades_to_no_knownList()
+    public void Pvp_PlayActions_ungenerated_token_idx_degrades_to_no_knownList()
     {
         var (s, a, b) = NewPvpSession();
         DriveToAfterReady(s, a);
@@ -268,6 +268,49 @@ public class BattleSessionDispatchTests
         Assert.That(pb.KnownList, Is.Null);
     }
 
+    [Test]
+    public void Pvp_PlayActions_reveals_token_generated_in_an_earlier_frame()
+    {
+        var (s, a, b) = NewPvpSession();
+        DriveToAfterReady(s, a);
+        DriveToAfterReady(s, b);
+
+        // Frame 1: A plays deck card idx 3 (a spell, hand 10 -> cemetery 30) whose fanfare ADDS
+        // token idx 31 (cardId 900111010) to A's hand (limbo 50 -> hand 10).
+        var gen = new Dictionary<string, object?>
+        {
+            ["playIdx"] = 3L,
+            ["type"] = 30L,
+            ["orderList"] = new List<object?>
+            {
+                new Dictionary<string, object?> { ["move"] = new Dictionary<string, object?>
+                    { ["idx"] = new List<object?> { 3L }, ["isSelf"] = 1L, ["from"] = 10L, ["to"] = 30L } },
+                new Dictionary<string, object?> { ["add"] = new Dictionary<string, object?>
+                    { ["idx"] = new List<object?> { 31L }, ["isSelf"] = 1L,
+                      ["card"] = new Dictionary<string, object?> { ["cardId"] = 900111010L } } },
+                new Dictionary<string, object?> { ["move"] = new Dictionary<string, object?>
+                    { ["idx"] = new List<object?> { 31L }, ["isSelf"] = 1L, ["from"] = 50L, ["to"] = 10L } },
+            },
+        };
+        var genRoutes = s.ComputeFrames(a, EnvWith(NetworkBattleUri.PlayActions, gen));
+        // The deck card itself reveals from the deck map; the token stays hidden (in hand).
+        var genBody = (PlayActionsBroadcastBody)genRoutes[0].Frame.Body;
+        Assert.That(genBody.KnownList!.Single().CardId, Is.EqualTo(100_011_010L), "deck card revealed");
+
+        // Frame 2 (later turn): A plays token idx 31 from hand (10) to field (20).
+        var play = MoveOrderList(idx: 31, from: 10, to: 20);
+        play["playIdx"] = 31L;
+        play["type"] = 30L;
+        var routes = s.ComputeFrames(a, EnvWith(NetworkBattleUri.PlayActions, play));
+
+        var pb = (PlayActionsBroadcastBody)routes[0].Frame.Body;
+        Assert.That(pb.PlayIdx, Is.EqualTo(31));
+        Assert.That(pb.KnownList, Is.Not.Null, "the token's identity was remembered from its add op");
+        Assert.That(pb.KnownList!.Single().Idx, Is.EqualTo(31));
+        Assert.That(pb.KnownList[0].CardId, Is.EqualTo(900_111_010L), "mined token cardId");
+        Assert.That(pb.KnownList[0].To, Is.EqualTo(20));
+    }
+
     [Test]
     public void Pvp_PlayActions_when_B_still_AwaitingSwap_drops()
     {

SVSim.UnitTests/BattleNode/Sessions/KnownListBuilderTests.cs

@@ -111,4 +111,95 @@ public class KnownListBuilderTests
         Assert.That(KnownListBuilder.RenameTargets(null), Is.Null);
         Assert.That(KnownListBuilder.RenameTargets(new List<object?>()), Is.Null);
     }
+
+    // An add op as it arrives in a RawBody: { "add": { "idx": [..], "isSelf": n, "card": { "cardId": n } } }
+    private static Dictionary<string, object?> AddOp(long[] idxs, long cardId, long isSelf = 1) => new()
+    {
+        ["add"] = new Dictionary<string, object?>
+        {
+            ["idx"] = idxs.Select(i => (object?)i).ToList(),
+            ["isSelf"] = isSelf,
+            ["card"] = new Dictionary<string, object?> { ["cardId"] = cardId },
+        }
+    };
+
+    [Test]
+    public void MineAddOps_yields_idx_to_cardId_for_every_idx_in_an_add_op()
+    {
+        var orderList = new List<object?> { AddOp(new[] { 31L, 32L }, 900111010L) };
+        var mined = KnownListBuilder.MineAddOps(orderList).ToList();
+
+        Assert.That(mined, Is.EquivalentTo(new[] { (31, 900111010L), (32, 900111010L) }));
+    }
+
+    [Test]
+    public void MineAddOps_skips_add_ops_for_the_opponent_isSelf_0()
+    {
+        // A card given to the opponent (isSelf:0) belongs in the other side's map — deferred.
+        var orderList = new List<object?> { AddOp(new[] { 31L }, 900111010L, isSelf: 0) };
+        Assert.That(KnownListBuilder.MineAddOps(orderList), Is.Empty);
+    }
+
+    [Test]
+    public void MineAddOps_skips_choice_adds_with_no_concrete_cardId()
+    {
+        // { "add": { "idx":[46], "card": { "candidates":[...] }, "isChoice":"1" } } — identity undetermined.
+        var orderList = new List<object?>
+        {
+            new Dictionary<string, object?>
+            {
+                ["add"] = new Dictionary<string, object?>
+                {
+                    ["idx"] = new List<object?> { 46L },
+                    ["isSelf"] = 1L,
+                    ["card"] = new Dictionary<string, object?>
+                    {
+                        ["candidates"] = new List<object?> { 810041260L, 101041020L },
+                    },
+                    ["isChoice"] = "1",
+                }
+            }
+        };
+        Assert.That(KnownListBuilder.MineAddOps(orderList), Is.Empty);
+    }
+
+    [Test]
+    public void MineAddOps_skips_copy_token_adds_with_baseIdx_and_no_cardId()
+    {
+        // RegisterCopyToken.MakeCardData → { "baseIdx": N, "isPremium": 0 } — no cardId, deferred.
+        var orderList = new List<object?>
+        {
+            new Dictionary<string, object?>
+            {
+                ["add"] = new Dictionary<string, object?>
+                {
+                    ["idx"] = new List<object?> { 33L },
+                    ["isSelf"] = 1L,
+                    ["card"] = new Dictionary<string, object?> { ["baseIdx"] = 12L, ["isPremium"] = 0L },
+                }
+            }
+        };
+        Assert.That(KnownListBuilder.MineAddOps(orderList), Is.Empty);
+    }
+
+    [Test]
+    public void MineAddOps_ignores_non_add_ops_and_null()
+    {
+        Assert.That(KnownListBuilder.MineAddOps(OrderListMove(3, 10, 20)), Is.Empty);
+        Assert.That(KnownListBuilder.MineAddOps(null), Is.Empty);
+    }
+
+    [Test]
+    public void MineAddOps_yields_from_multiple_add_ops_in_one_orderList()
+    {
+        var orderList = new List<object?>
+        {
+            new Dictionary<string, object?> { ["move"] = new Dictionary<string, object?>
+                { ["idx"] = new List<object?> { 3L }, ["isSelf"] = 1L, ["from"] = 10L, ["to"] = 30L } },
+            AddOp(new[] { 31L }, 900111010L),
+            AddOp(new[] { 32L }, 900811090L),
+        };
+        var mined = KnownListBuilder.MineAddOps(orderList).ToList();
+        Assert.That(mined, Is.EquivalentTo(new[] { (31, 900111010L), (32, 900811090L) }));
+    }
 }