diff --git a/SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs b/SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs
index 30b100d..da229e1 100644
--- a/SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs
+++ b/SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs
@@ -5,10 +5,13 @@ using SVSim.BattleNode.Sessions;
namespace SVSim.BattleNode.Sessions.Dispatch;
/// 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 knownList. Generated tokens (cardIds mined from
-/// orderList add ops) are recorded into the SAME
-/// map via ; a reveal-gate set is still future.
+/// post-swap hands, plus the per-side idx->cardId map used as the FALLBACK identity source for the
+/// opponent-facing knownList. As of M-HC-4f the played card's identity is ENGINE-first — the handler
+/// reads SessionBattleEngine.PlayedCardId and uses this map only as the fallback (non-engine session,
+/// or a token case the engine doesn't resolve at a wire idx). The map still holds deck cards (seeded from the
+/// shuffled deck) and the wire-mined generated/choice/copy/cross-side token identities (recorded via
+/// ) — those token cases remain wire-mined pending an engine-read proof
+/// (TODO(M-HC-4f) in PlayActionsHandler).
internal sealed class BattleSessionState
{
/// The one random value chosen per battle. Every per-battle RNG (shared effect seed,
diff --git a/SVSim.BattleNode/Sessions/Dispatch/Handlers/PlayActionsHandler.cs b/SVSim.BattleNode/Sessions/Dispatch/Handlers/PlayActionsHandler.cs
index 4d59dce..d7b5d86 100644
--- a/SVSim.BattleNode/Sessions/Dispatch/Handlers/PlayActionsHandler.cs
+++ b/SVSim.BattleNode/Sessions/Dispatch/Handlers/PlayActionsHandler.cs
@@ -3,13 +3,16 @@ using SVSim.BattleNode.Protocol.Bodies;
namespace SVSim.BattleNode.Sessions.Dispatch.Handlers;
-/// 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),
-/// keyAction.selectCard (choice picks), or a baseIdx copy resolved against the side's map — all mined
-/// on earlier (or the same) frames; an un-generated token idx still degrades to {playIdx,type}
-/// (no knownList). Bot drop (no rule).
+/// PvP PlayActions translator. Synthesizes the opponent-facing knownList from the engine-resolved
+/// played card + 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).
+/// The played card's IDENTITY (cardId), cost, spellboost, clan and tribe are all ENGINE-sourced (M-HC-3/4);
+/// the identity is engine-first with a wire-mined idx->cardId fallback (deck card or recorded token). The
+/// fallback still covers the token cases the engine doesn't headlessly resolve at a wire idx — choice/Discover
+/// picks (keyAction.selectCard), baseIdx copies, and cross-side (isSelf:0) gifts — all WIRE-MINED on earlier
+/// (or the same) frames via the Record*From calls below (TODO(M-HC-4f): retire once engine-proven at a wire
+/// idx). An un-resolvable token idx (no engine id, no mined entry) degrades to {playIdx,type} (no knownList).
+/// Bot drop (no rule).
internal sealed class PlayActionsHandler : IFrameHandler
{
public IReadOnlyList Handle(FrameDispatchContext ctx)
@@ -39,6 +42,10 @@ internal sealed class PlayActionsHandler : IFrameHandler
ctx.State.RecordCopyTokensFrom(ctx.From, ctx.Other, orderList);
var deckMap = ctx.State.GetOrSeedDeckMap(ctx.From);
+ // The wire-mined idx->cardId fallback identity (deck card, or a token recorded into the map above by
+ // the Record*From calls). Used ONLY as the engine-read's fallback below — 0 when the idx isn't in the map.
+ long mappedCardId = deckMap.TryGetValue(playIdx, out var mid) ? mid : 0L;
+
// The ENGINE-RESOLVED play-time cost (M-HC-3a). The conductor's ShadowIngest already ran
// engine.Receive for THIS frame before this handler runs, so the engine has resolved the play and
// PlayedCardCost reads the discounted cost it actually charged (spellboost + board modifiers folded
@@ -63,8 +70,22 @@ internal sealed class PlayActionsHandler : IFrameHandler
int playedClan = ctx.Engine.PlayedCardClan(senderSeat, playIdx, fallback: 0);
string playedTribe = ctx.Engine.PlayedCardTribe(senderSeat, playIdx, fallback: "0");
+ // The card IDENTITY is now ALSO engine-sourced (M-HC-4f): read the engine-resolved CardId off the played
+ // card, falling back to the wire-mined idx->cardId map when the engine doesn't resolve it. PROVEN
+ // engine-resolved (each backed by a HeadlessConductorTests PlayedCardId_* test): a DECK card and a
+ // receive-path SUBSTITUTED/revealed token (the engine seats the wire id at the wire idx). The fallback
+ // is LOAD-BEARING, not vestigial: it still supplies the identity for (a) a non-engine session (gate not
+ // acquired) and (b) the token cases the engine doesn't headlessly resolve AT A WIRE IDX — choice/Discover
+ // tokens (autonomous token_draw seats them at engine Index 0 headless), copy/clone tokens, and cross-side
+ // (isSelf:0) gifts. Those remain WIRE-MINED via the Record*From calls above; retiring that mining is gated
+ // on proving the engine seats them at a wire idx, which the current headless harness can't fixture cheaply.
+ // TODO(M-HC-4f): once a node-native (or full wire add-op/replace) fixture proves the engine resolves a
+ // choice token, a copy token and a cross-side gift at their WIRE idx, retire MineChoicePicks/MineCopyTokens/
+ // the cross-side MineAddOps branch + the matching Record* bookkeeping and drop this fallback to deck-only.
+ long playedCardId = ctx.Engine.PlayedCardId(senderSeat, playIdx, fallback: mappedCardId);
+
var played = KnownListBuilder.BuildPlayedCard(
- deckMap, playIdx, orderList, cost: playedCost, spellboost: playedSpellboost,
+ playIdx, playedCardId, orderList, cost: playedCost, spellboost: playedSpellboost,
clan: playedClan, tribe: playedTribe);
var oppoTargets = KnownListBuilder.RenameTargets(entries.GetValueOrDefault(WireKeys.TargetList));
diff --git a/SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs b/SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs
index 542c9d8..6542c8d 100644
--- a/SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs
+++ b/SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs
@@ -10,23 +10,29 @@ namespace SVSim.BattleNode.Sessions.Dispatch;
internal static class KnownListBuilder
{
/// The played card's knownList entry, or null when its identity can't be synthesized
- /// (token idx not in the deck map, or no matching move op). ,
- /// , and are ALL
- /// ENGINE-SOURCED (M-HC-3a/3b/4e) — the handler reads them off the shadow engine
- /// (SessionBattleEngine.PlayedCardCost/PlayedCardSpellboost/PlayedCardClan/
- /// PlayedCardTribe) and passes them in; all land on the entry verbatim. The wire-derived
- /// spellboost bookkeeping is retired — the engine owns cost and count by construction (cost folds the
- /// spellboost discount in already; the count rides the entry only to stay prod-faithful, prod sends the
- /// real count here). / are the LIVE (skill-applied)
- /// values the engine resolved — prod always sends both on every knownList entry (clan int, tribe the
- /// comma-joined int string, "0" for none). Prod's client reads cost straight into the card's cost model
- /// (NetworkBattleReceiver), so a vanilla play resolves to its base cost and count 0. attachTarget
- /// stays "".
+ /// (the played idx resolves to no card identity, or there's no matching move op). ,
+ /// , , and
+ /// are ALL ENGINE-SOURCED at the call site (M-HC-3a/3b/4e/4f) — the handler reads them off the shadow engine
+ /// (SessionBattleEngine.PlayedCardId/PlayedCardCost/PlayedCardSpellboost/PlayedCardClan/
+ /// PlayedCardTribe) and passes them in; all land on the entry verbatim.
+ /// is the engine-resolved TRUE identity of the played card (M-HC-4f). The
+ /// handler computes it engine-first with a fallback: engine.PlayedCardId(seat, playIdx, fallback: deckMapId),
+ /// where deckMapId is the wire-mined idx→cardId entry (deck card or recorded token). So an engine-backed
+ /// session emits the engine identity; a non-engine session (or an idx the engine doesn't headlessly resolve at a
+ /// wire idx — choice/copy/cross-side tokens, still wire-mined; see TODO(M-HC-4f) in PlayActionsHandler) falls back
+ /// to the mined map. A of 0 (no engine id AND no mined entry) means an un-synthesizable
+ /// play → null (no knownList; the play degrades to {playIdx,type}).
+ /// The wire-derived spellboost bookkeeping is retired — the engine owns cost and count by construction (cost folds
+ /// the spellboost discount in already; the count rides the entry only to stay prod-faithful, prod sends the real
+ /// count here). / are the LIVE (skill-applied) values the engine
+ /// resolved — prod always sends both on every knownList entry (clan int, tribe the comma-joined int string, "0"
+ /// for none). Prod's client reads cost straight into the card's cost model (NetworkBattleReceiver), so a
+ /// vanilla play resolves to its base cost and count 0. attachTarget stays "".
public static KnownCardEntry? BuildPlayedCard(
- IReadOnlyDictionary deckMap, int playIdx, object? orderList,
+ int playIdx, long cardId, object? orderList,
int cost = 0, int spellboost = 0, int clan = 0, string tribe = "0")
{
- if (!deckMap.TryGetValue(playIdx, out var cardId)) return null;
+ if (cardId == 0) return null; // no engine id AND no mined/deck-map fallback → can't synthesize an identity
var to = ExtractMoveTo(orderList, playIdx);
if (to is null) return null;
return new KnownCardEntry(
diff --git a/SVSim.BattleNode/Sessions/Engine/SessionBattleEngine.cs b/SVSim.BattleNode/Sessions/Engine/SessionBattleEngine.cs
index 0c8fc5c..a198da8 100644
--- a/SVSim.BattleNode/Sessions/Engine/SessionBattleEngine.cs
+++ b/SVSim.BattleNode/Sessions/Engine/SessionBattleEngine.cs
@@ -279,6 +279,29 @@ internal sealed class SessionBattleEngine
return card?.SpellChargeCount ?? fallback;
}
+ /// The engine-RESOLVED card identity (wire cardId) of the card whose engine Index ==
+ /// on (M-HC-4f), read straight off
+ /// — the TRUE id the engine resolved during the conductor's
+ /// ShadowIngest (engine.Receive ran BEFORE this read). This is the authoritative identity for
+ /// EVERY card the engine seats, retiring the wire-mined idx→cardId bookkeeping for the played card:
+ ///
+ /// - a DECK card carries its dealt id (the seeded shuffled-deck identity);
+ /// - a GENERATED token carries the wire id CreateActualCard/ReplaceReceivedCards stamped on it
+ /// (M-HC-2 proved reveal seats the wire cardId);
+ /// - a CHOICE/Discover token carries the CHOSEN id (M-HC-4c proved the chosen token lands with its true id);
+ /// - a COPY/clone token carries the COPIED id (the engine copies the source card at baseIdx).
+ ///
+ /// Same post-resolution zone search + degrade-to- contract as
+ /// : no engine / no card → , so a non-engine session
+ /// (the single-active-engine gate left this session without an owned engine) keeps emitting the deck-map id via
+ /// the caller's fallback, never crashing.
+ public long PlayedCardId(bool playerSeat, int idx, long fallback = 0)
+ {
+ if (_mgr is null) return fallback;
+ var card = FindByIndex(Seat(playerSeat), idx);
+ return card is null ? fallback : card.CardId;
+ }
+
/// The engine-RESOLVED clan of the card whose engine Index == on
/// (M-HC-4e), as the int ClanType ordinal prod sends on the
/// knownList entry (e.g. clan:8 in the tk2 capture). Reads , whose
@@ -307,8 +330,9 @@ internal sealed class SessionBattleEngine
/// prod no-tribe form — NEVER empty, which is wire-illegal: prod always sends tribe as a non-empty string,
/// the client reads it via item.Value.ToString() at NetworkBattleReceiver.cs:2382). The degrade is
/// LIVE, not dead: a second concurrent battle that loses the single-active-engine gate has _mgr is null
- /// yet still emits a knownList entry (KnownListBuilder.BuildPlayedCard gates on the deck map, not engine
- /// ownership), so this path must hand back a legal wire value.
+ /// yet still emits a knownList entry (the handler resolves the identity via the deck-map/mined fallback when
+ /// the engine read degrades, so BuildPlayedCard still synthesizes an entry), so this path must hand back a
+ /// legal wire value.
public string PlayedCardTribe(bool playerSeat, int idx, string fallback = "0")
{
if (_mgr is null) return fallback;
diff --git a/SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs b/SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs
index 589dcb7..4353758 100644
--- a/SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs
+++ b/SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs
@@ -282,7 +282,7 @@ public class CaptureConformanceTests
}
}
};
- var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(deckMap, 17, orderList);
+ var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(17, deckMap[17], orderList);
Assert.That(entry, Is.Not.Null);
var body = new SVSim.BattleNode.Protocol.Bodies.PlayActionsBroadcastBody(
@@ -333,7 +333,7 @@ public class CaptureConformanceTests
new Dictionary { ["move"] = new Dictionary
{ ["idx"] = new List { 38L }, ["isSelf"] = 1L, ["from"] = 10L, ["to"] = 20L } },
};
- var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(map, 38, playOrderList);
+ var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(38, 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(
@@ -456,7 +456,7 @@ public class CaptureConformanceTests
}
};
- var played = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(deckMap, 18, orderList);
+ var played = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(18, deckMap[18], orderList);
var keyActionOut = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.StripKeyActionForOpponent(keyActionIn);
var body = new SVSim.BattleNode.Protocol.Bodies.PlayActionsBroadcastBody(
PlayIdx: 18, Type: 30, KnownList: new[] { played! }, OppoTargetList: null, KeyAction: keyActionOut);
@@ -520,7 +520,7 @@ public class CaptureConformanceTests
new Dictionary { ["move"] = new Dictionary
{ ["idx"] = new List { 46L }, ["isSelf"] = 1L, ["from"] = 10L, ["to"] = 20L } },
};
- var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(map, 46, playOrderList);
+ var entry = SVSim.BattleNode.Sessions.Dispatch.KnownListBuilder.BuildPlayedCard(46, map[46], playOrderList);
Assert.That(entry, Is.Not.Null, "the mined choice pick resolves to a knownList entry");
var body = new SVSim.BattleNode.Protocol.Bodies.PlayActionsBroadcastBody(
diff --git a/SVSim.UnitTests/BattleNode/Integration/HeadlessConductorTests.cs b/SVSim.UnitTests/BattleNode/Integration/HeadlessConductorTests.cs
index ba7b78f..7b37fa6 100644
--- a/SVSim.UnitTests/BattleNode/Integration/HeadlessConductorTests.cs
+++ b/SVSim.UnitTests/BattleNode/Integration/HeadlessConductorTests.cs
@@ -1285,6 +1285,117 @@ public class HeadlessConductorTests
Assert.That(body.KnownList[0].Tribe, Is.Not.EqualTo("0"), "non-vacuity: tribe must not be the \"0\" default");
}
+ // === M-HC-4f: engine-resolved token identity (cardId) on the knownList =========================
+ //
+ // The opponent-facing knownList[].cardId is now ENGINE-sourced (PlayActionsHandler reads
+ // SessionBattleEngine.PlayedCardId off the resolved card). These tests prove the engine carries the TRUE
+ // id for each token case the retired wire-mining used to handle — deck card, generated/substituted token,
+ // and choice/Discover token — so the wire-mined idx→cardId bookkeeping for the PLAYED card is redundant.
+ // (The deck-map remains as the non-engine-session fallback.)
+
+ [Test]
+ public void PlayedCardId_reads_engine_resolved_deck_card_id()
+ {
+ // BASELINE (proves the read mechanism): a plain DECK card. Play it and assert PlayedCardId returns the
+ // seeded deck id — the same value the deck-map fallback would have supplied, read off the engine.
+ var deck = new List { NodeNativeBattleHarness.VanillaFollowerId };
+ deck.AddRange(NodeNativeBattleHarness.DefaultDeck());
+ deck = deck.GetRange(0, 30);
+ using var harness = NodeNativeBattleHarness.Create(seatADeck: deck);
+
+ Assert.That(harness.Push(NetworkBattleUri.Deal, DealBody(), isPlayerSeat: true).Accepted, Is.True, "Deal");
+ int playIdx = harness.PlayerHandCardIndex(0);
+ long dealtId = harness.HandCardId(playerSeat: true, handPos: 0); // the engine-seated deck identity at this idx
+ Assert.That(harness.Push(NetworkBattleUri.PlayActions, PlayBody(playIdx), isPlayerSeat: true).Accepted,
+ Is.True, "deck-card play");
+
+ Assert.That(harness.PlayedCardId(playerSeat: true, idx: playIdx), Is.EqualTo(dealtId),
+ "PlayedCardId must return the engine-resolved deck card identity");
+ // Cross-check against the deck-map (the retired path's source) so we KNOW the engine read is equivalent
+ // for a deck card — the behavior-preserving guarantee for the common case.
+ Assert.That(dealtId, Is.EqualTo(harness.SeatADeck[playIdx - 1]),
+ "the dealt id equals the node's shuffled deck-map id at this idx (engine read == deck-map fallback)");
+ }
+
+ [Test]
+ public void PlayedCardId_degrades_to_fallback_for_unknown_idx()
+ {
+ // Graceful degradation (mirrors PlayedCardCost_degrades_*): a non-engine session / unmapped idx returns
+ // the caller's fallback — the deck-map id the handler hands in — never crashing.
+ using var harness = NodeNativeBattleHarness.Create();
+ Assert.That(harness.PlayedCardId(playerSeat: true, idx: 9999, fallback: 424242L), Is.EqualTo(424242L));
+ }
+
+ [Test]
+ public void PlayedCardId_reads_substituted_token_identity_off_the_board()
+ {
+ // GENERATED/SUBSTITUTED TOKEN: M-HC-2 proved a reveal seats the WIRE cardId (overriding the seeded id)
+ // via CreateActualCard. This proves PlayedCardId then reads that TRUE id off the resolved card — so a
+ // later play of a generated token reveals its real identity engine-sourced, NOT the wire-mined map.
+ // Reuse the substitution fixture: seat B's deck is uniformly Z; the reveal substitutes W at idx 1.
+ const long Z = NodeNativeBattleHarness.VanillaFollowerId; // seeded identity
+ const long W = NodeNativeBattleHarness.AltVanillaFollowerId; // the wire (revealed) identity
+ var seatBDeck = Enumerable.Repeat(Z, 30).ToList();
+ using var harness = NodeNativeBattleHarness.Create(seatBDeck: seatBDeck);
+
+ Assert.That(harness.Push(NetworkBattleUri.Deal, DealBody(), isPlayerSeat: true).Accepted, Is.True, "Deal");
+ Assert.That(harness.Push(NetworkBattleUri.Swap, SwapBody(), isPlayerSeat: true).Accepted, Is.True, "Swap");
+ Assert.That(harness.Push(NetworkBattleUri.Ready, ReadyBody(), isPlayerSeat: true).Accepted, Is.True, "Ready");
+ Assert.That(harness.Push(NetworkBattleUri.TurnStart, TurnStartBody(), isPlayerSeat: true).Accepted, Is.True, "turn1 TurnStart");
+ Assert.That(harness.Push(NetworkBattleUri.TurnEnd, TurnEndBody(), isPlayerSeat: true).Accepted, Is.True, "turn1 TurnEnd");
+ Assert.That(harness.Push(NetworkBattleUri.TurnStart, TurnStartBody(), isPlayerSeat: false).Accepted, Is.True, "turn2 TurnStart (B)");
+
+ Assert.That(harness.Push(NetworkBattleUri.PlayActions, RevealPlayBody(idx: 1, cardId: W), isPlayerSeat: false).Accepted,
+ Is.True, "seat B reveal-play");
+ int boardIdx = harness.InPlayCardIndex(playerSeat: false, boardPos: 0);
+
+ // THE assertion: PlayedCardId reads the SUBSTITUTED wire id W off the resolved board card, not the seeded Z.
+ Assert.That(harness.PlayedCardId(playerSeat: false, idx: boardIdx), Is.EqualTo(W),
+ "PlayedCardId must read the engine-seated (substituted) wire cardId, not the seeded deck id");
+ Assert.That(harness.PlayedCardId(playerSeat: false, idx: boardIdx), Is.Not.EqualTo(Z),
+ "non-vacuity: the read is the wire id, NOT the seeded identity at that idx");
+ }
+
+ [Test]
+ [Explicit("M-HC-4f UNPROVEN case: the engine's autonomous token_draw seats the chosen token at engine " +
+ "Index 0 headless (NOT a wire idx past the deck), so PlayedCardId cannot address it by idx — it " +
+ "would collide with the leader (also Index 0). This test DOCUMENTS the gap that keeps " +
+ "MineChoicePicks wire-mining alive (see TODO(M-HC-4f) in PlayActionsHandler). Run explicitly to " +
+ "re-verify the gap; it asserts the FINDING (Index 0), not a passing engine read.")]
+ public void PlayedCardId_choice_token_seats_at_index_zero_headless_GAP()
+ {
+ // CHOICE/Discover TOKEN — the case the engine does NOT resolve at a wire idx headless. Playing the choice
+ // card (127011010) and choosing token B (120011010) lands it in hand with the correct IDENTITY, but at
+ // engine Index 0 (the autonomous token_draw skill path, not the wire add-op/replace path the relay uses).
+ // PlayedCardId(seat, 0) would therefore read the LEADER (Index 0), not the token — so the engine cannot
+ // replace MineChoicePicks for this case. (In a real relay the token rides a wire add op that seats a dummy
+ // at a non-zero idx, then a replace substitutes the real id there — a path not reproducible cheaply here.)
+ var seatADeck = Enumerable.Repeat(NodeNativeBattleHarness.ChoiceCardId, 30).ToList();
+ using var harness = NodeNativeBattleHarness.Create(seatADeck: seatADeck);
+
+ Assert.That(harness.Push(NetworkBattleUri.Deal, DealBody(), isPlayerSeat: true).Accepted, Is.True, "Deal");
+ Assert.That(harness.Push(NetworkBattleUri.Swap, SwapBody(), isPlayerSeat: true).Accepted, Is.True, "Swap");
+ Assert.That(harness.Push(NetworkBattleUri.Ready, ReadyBody(), isPlayerSeat: true).Accepted, Is.True, "Ready");
+ Assert.That(harness.Push(NetworkBattleUri.TurnStart, TurnStartBody(), isPlayerSeat: true).Accepted, Is.True, "turn1 TurnStart");
+
+ int choiceIdx = harness.HandCardIndex(playerSeat: true, handPos: 0);
+ const long chosen = NodeNativeBattleHarness.ChoiceTokenB; // 120011010
+ Assert.That(harness.Push(NetworkBattleUri.PlayActions,
+ NodeNativeBattleHarness.ChoicePlayBody(choiceIdx, NodeNativeBattleHarness.ChoiceCardId, chosen),
+ isPlayerSeat: true).Accepted,
+ Is.True, "choice play (chose token B)");
+
+ // The chosen token IS in hand with the right identity (M-HC-4c proved this) ...
+ int tokenIdx = -1;
+ for (int i = 0; i < harness.HandCount(playerSeat: true); i++)
+ if (harness.HandCardId(playerSeat: true, i) == (int)chosen) { tokenIdx = harness.HandCardIndex(playerSeat: true, i); break; }
+ Assert.That(tokenIdx, Is.GreaterThanOrEqualTo(0), "the chosen token (B) must be in seat A's hand");
+
+ // ... but its engine Index is 0 — the documented gap. PlayedCardId(seat, 0) reads the leader, not the token.
+ Assert.That(tokenIdx, Is.EqualTo(0),
+ "FINDING: the autonomous token_draw seats the chosen token at engine Index 0 headless — not addressable by a wire idx");
+ }
+
// The hand POSITION (0-based) of the seat-A hand card with the given engine Index, or -1. Lets a test
// re-derive a HandCardId(seat, pos) lookup from an engine Index it already located by identity.
private static int FindHandPosByEngineIdx(NodeNativeBattleHarness harness, int engineIdx)
diff --git a/SVSim.UnitTests/BattleNode/Integration/NodeNativeBattleHarness.cs b/SVSim.UnitTests/BattleNode/Integration/NodeNativeBattleHarness.cs
index 434e8d7..4634df3 100644
--- a/SVSim.UnitTests/BattleNode/Integration/NodeNativeBattleHarness.cs
+++ b/SVSim.UnitTests/BattleNode/Integration/NodeNativeBattleHarness.cs
@@ -242,6 +242,12 @@ internal sealed class NodeNativeBattleHarness : IDisposable
public int DeckCount(bool playerSeat) => Engine.DeckCount(playerSeat);
public int Turn(bool playerSeat) => Engine.Turn(playerSeat);
+ /// The engine-resolved wire cardId of the card at engine on the
+ /// given seat (M-HC-4f). Pass-through to SessionBattleEngine.PlayedCardId — the TRUE id the engine
+ /// seated (deck id / token id / chosen-token id / copied id), the value the handler now sources for the
+ /// opponent-facing knownList instead of the wire-mined map.
+ public long PlayedCardId(bool playerSeat, int idx, long fallback = 0) => Engine.PlayedCardId(playerSeat, idx, fallback);
+
/// The engine Index of seat A's hand card at (the playIdx a
/// Play frame would carry to play it).
public int PlayerHandCardIndex(int handPos) => Engine.HandCardIndex(playerSeat: true, handPos);
diff --git a/SVSim.UnitTests/BattleNode/Sessions/KnownListBuilderTests.cs b/SVSim.UnitTests/BattleNode/Sessions/KnownListBuilderTests.cs
index 3c04cb9..2787495 100644
--- a/SVSim.UnitTests/BattleNode/Sessions/KnownListBuilderTests.cs
+++ b/SVSim.UnitTests/BattleNode/Sessions/KnownListBuilderTests.cs
@@ -62,19 +62,19 @@ public class KnownListBuilderTests
}
[Test]
- public void BuildPlayedCard_returns_null_for_deck_card_with_no_matching_move_op()
+ public void BuildPlayedCard_returns_null_for_card_with_no_matching_move_op()
{
- // idx is in the deck, but the orderList has no move op for it → can't synthesize.
- var deckMap = new Dictionary { [3] = 128821011L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, playIdx: 3, orderList: OrderListMove(7, 10, 20));
+ // A resolved cardId, but the orderList has no move op for the played idx → can't synthesize.
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 128821011L, orderList: OrderListMove(7, 10, 20));
Assert.That(entry, Is.Null);
}
[Test]
- public void BuildPlayedCard_synthesizes_entry_for_deck_card()
+ public void BuildPlayedCard_synthesizes_entry_from_engine_sourced_cardId()
{
- var deckMap = new Dictionary { [3] = 128821011L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, playIdx: 3, orderList: OrderListMove(3, 10, 20));
+ // M-HC-4f: the handler resolves the cardId engine-first (PlayedCardId, deck-map/mined fallback) and passes
+ // it in; BuildPlayedCard lands it on the entry verbatim.
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 128821011L, orderList: OrderListMove(3, 10, 20));
Assert.That(entry, Is.Not.Null);
Assert.That(entry!.Idx, Is.EqualTo(3));
@@ -90,8 +90,7 @@ public class KnownListBuilderTests
{
// M-HC-3a: the handler reads the engine-resolved play-time cost and passes it in; BuildPlayedCard
// lands it on the entry verbatim. (A wrong cost yields a different field — non-vacuity.)
- var deckMap = new Dictionary { [3] = 101314020L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, playIdx: 3, orderList: OrderListMove(3, 10, 20), cost: 3);
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 101314020L, orderList: OrderListMove(3, 10, 20), cost: 3);
Assert.That(entry, Is.Not.Null);
Assert.That(entry!.Cost, Is.EqualTo(3));
}
@@ -102,17 +101,17 @@ public class KnownListBuilderTests
// M-HC-3b: the handler reads the engine-resolved spell-charge count
// (SessionBattleEngine.PlayedCardSpellboost) and passes it in; BuildPlayedCard lands it on the
// entry verbatim. (Default 0 vs a non-zero value is the non-vacuity.)
- var deckMap = new Dictionary { [3] = 101314020L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, playIdx: 3, orderList: OrderListMove(3, 10, 20), cost: 3, spellboost: 2);
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 101314020L, orderList: OrderListMove(3, 10, 20), cost: 3, spellboost: 2);
Assert.That(entry, Is.Not.Null);
Assert.That(entry!.Spellboost, Is.EqualTo(2));
}
[Test]
- public void BuildPlayedCard_returns_null_for_token_idx_not_in_deck()
+ public void BuildPlayedCard_returns_null_for_zero_cardId()
{
- var deckMap = new Dictionary { [3] = 128821011L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, playIdx: 31, orderList: OrderListMove(31, 10, 20));
+ // M-HC-4f: cardId 0 means the engine resolved no id AND the deck-map/mined fallback had no entry for the
+ // idx → un-synthesizable identity → null (the play degrades to {playIdx,type}, no knownList).
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 31, cardId: 0L, orderList: OrderListMove(31, 10, 20));
Assert.That(entry, Is.Null);
}
@@ -121,8 +120,7 @@ public class KnownListBuilderTests
{
// A vanilla play emits spellboost 0 (the engine resolves no spell-charge for a non-boosted card,
// so the handler's PlayedCardSpellboost read is 0 and the param defaults to 0).
- var deckMap = new Dictionary { [3] = 101311010L };
- Assert.That(KnownListBuilder.BuildPlayedCard(deckMap, 3, OrderListMove(3, 10, 20))!.Spellboost, Is.EqualTo(0));
+ Assert.That(KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 101311010L, orderList: OrderListMove(3, 10, 20))!.Spellboost, Is.EqualTo(0));
}
[Test]
@@ -131,9 +129,8 @@ public class KnownListBuilderTests
// M-HC-4e: the handler reads the engine-resolved clan/tribe
// (SessionBattleEngine.PlayedCardClan / PlayedCardTribe) and passes them in; BuildPlayedCard lands
// them on the entry verbatim. (A wrong clan/tribe yields a different field — non-vacuity.)
- var deckMap = new Dictionary { [3] = 101314020L };
var entry = KnownListBuilder.BuildPlayedCard(
- deckMap, playIdx: 3, orderList: OrderListMove(3, 10, 20), cost: 3, spellboost: 2, clan: 8, tribe: "7,16");
+ playIdx: 3, cardId: 101314020L, orderList: OrderListMove(3, 10, 20), cost: 3, spellboost: 2, clan: 8, tribe: "7,16");
Assert.That(entry, Is.Not.Null);
Assert.That(entry!.Clan, Is.EqualTo(8));
Assert.That(entry.Tribe, Is.EqualTo("7,16"));
@@ -145,8 +142,7 @@ public class KnownListBuilderTests
// A play whose engine read degraded (single-active-engine gate: _mgr null → the accessor fallback)
// emits clan 0 (ClanType.ALL ordinal) and tribe "0" (the prod no-tribe form, NEVER empty —
// empty is wire-illegal). The param defaults match the accessor fallbacks.
- var deckMap = new Dictionary { [3] = 101311010L };
- var entry = KnownListBuilder.BuildPlayedCard(deckMap, 3, OrderListMove(3, 10, 20));
+ var entry = KnownListBuilder.BuildPlayedCard(playIdx: 3, cardId: 101311010L, orderList: OrderListMove(3, 10, 20));
Assert.That(entry, Is.Not.Null);
Assert.That(entry!.Clan, Is.EqualTo(0));
Assert.That(entry.Tribe, Is.EqualTo("0"));