refactor(battlenode): engine-first token identity (cardId); keep wire-mining fallback (M-HC-4f, partial)

Source the played card's opponent-facing knownList[].cardId off the shadow engine
(SessionBattleEngine.PlayedCardId -> BattleCardBase.CardId), engine-first with the
wire-mined idx->cardId map as the fallback. PROVEN engine-resolved (each backed by a
HeadlessConductorTests PlayedCardId_* test): deck cards and receive-path substituted/
revealed tokens (engine seats the wire id at the wire idx).

PARTIAL retirement: the wire-mining bookkeeping (MineAddOps/MineChoicePicks/MineCopyTokens
+ Record*From) is KEPT as the load-bearing fallback. The choice/Discover, copy/clone and
cross-side (isSelf:0) token cases are NOT proven to resolve at a wire idx headless — the
autonomous token_draw path seats a chosen token at engine Index 0 (would collide with the
leader), and copy/cross-side aren't cheaply fixturable. Deleting their mining on faith
would silently corrupt opponent reveals, so it stays behind a TODO(M-HC-4f) gate.

- SessionBattleEngine.PlayedCardId: new accessor mirroring PlayedCardClan/Tribe.
- BuildPlayedCard: signature deckMap->explicit cardId; null on cardId==0 (no engine id AND
  no mined/deck-map fallback).
- PlayActionsHandler: cardId = engine.PlayedCardId(seat, idx, fallback: mapped) ; mining retained.
- Tests: PlayedCardId_* (deck/substituted/degrade pass; choice-gap [Explicit] documents the
  Index-0 finding). KnownListBuilder + CaptureConformance call-sites updated to new signature.

Full BattleNode suite 263/263 green; HeadlessConductorTests 27/27; drift clean; no Engine edits.

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

SVSim.BattleNode/Sessions/Dispatch/BattleSessionState.cs

@@ -5,10 +5,13 @@ using SVSim.BattleNode.Sessions;
 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>. Generated tokens (cardIds mined from
-/// 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>
+/// post-swap hands, plus the per-side idx->cardId map used as the FALLBACK identity source for the
+/// opponent-facing <c>knownList</c>. As of M-HC-4f the played card's identity is ENGINE-first — the handler
+/// reads <c>SessionBattleEngine.PlayedCardId</c> 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
+/// <see cref="RecordToken"/>) — those token cases remain wire-mined pending an engine-read proof
+/// (TODO(M-HC-4f) in <c>PlayActionsHandler</c>).</summary>
 internal sealed class BattleSessionState
 {
     /// <summary>The one random value chosen per battle. Every per-battle RNG (shared effect seed,

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

@@ -3,13 +3,16 @@ using SVSim.BattleNode.Protocol.Bodies;
 
 namespace SVSim.BattleNode.Sessions.Dispatch.Handlers;
 
-/// <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),
-/// 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).</summary>
+/// <summary>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).</summary>
 internal sealed class PlayActionsHandler : IFrameHandler
 {
     public IReadOnlyList<DispatchRoute> 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));
 

SVSim.BattleNode/Sessions/Dispatch/KnownListBuilder.cs

@@ -10,23 +10,29 @@ namespace SVSim.BattleNode.Sessions.Dispatch;
 internal static class KnownListBuilder
 {
     /// <summary>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). <paramref name="cost"/>,
-    /// <paramref name="spellboost"/>, <paramref name="clan"/> and <paramref name="tribe"/> are ALL
-    /// ENGINE-SOURCED (M-HC-3a/3b/4e) — the handler reads them off the shadow engine
-    /// (<c>SessionBattleEngine.PlayedCardCost</c>/<c>PlayedCardSpellboost</c>/<c>PlayedCardClan</c>/
-    /// <c>PlayedCardTribe</c>) 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). <paramref name="clan"/>/<paramref name="tribe"/> 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
-    /// (<c>NetworkBattleReceiver</c>), so a vanilla play resolves to its base cost and count 0. attachTarget
-    /// stays "".</summary>
+    /// (the played idx resolves to no card identity, or there's no matching move op). <paramref name="cardId"/>,
+    /// <paramref name="cost"/>, <paramref name="spellboost"/>, <paramref name="clan"/> and <paramref name="tribe"/>
+    /// are ALL ENGINE-SOURCED at the call site (M-HC-3a/3b/4e/4f) — the handler reads them off the shadow engine
+    /// (<c>SessionBattleEngine.PlayedCardId</c>/<c>PlayedCardCost</c>/<c>PlayedCardSpellboost</c>/<c>PlayedCardClan</c>/
+    /// <c>PlayedCardTribe</c>) and passes them in; all land on the entry verbatim.
+    /// <para><paramref name="cardId"/> is the engine-resolved TRUE identity of the played card (M-HC-4f). The
+    /// handler computes it engine-first with a fallback: <c>engine.PlayedCardId(seat, playIdx, fallback: deckMapId)</c>,
+    /// where <c>deckMapId</c> 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 <paramref name="cardId"/> of 0 (no engine id AND no mined entry) means an un-synthesizable
+    /// play → null (no knownList; the play degrades to {playIdx,type}).</para>
+    /// 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). <paramref name="clan"/>/<paramref name="tribe"/> 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 (<c>NetworkBattleReceiver</c>), so a
+    /// vanilla play resolves to its base cost and count 0. attachTarget stays "".</summary>
     public static KnownCardEntry? BuildPlayedCard(
-        IReadOnlyDictionary<int, long> 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(

SVSim.BattleNode/Sessions/Engine/SessionBattleEngine.cs

@@ -279,6 +279,29 @@ internal sealed class SessionBattleEngine
         return card?.SpellChargeCount ?? fallback;
     }
 
+    /// <summary>The engine-RESOLVED card identity (wire <c>cardId</c>) of the card whose engine <c>Index</c> ==
+    /// <paramref name="idx"/> on <paramref name="playerSeat"/> (M-HC-4f), read straight off
+    /// <see cref="BattleCardBase.CardId"/> — the TRUE id the engine resolved during the conductor's
+    /// <c>ShadowIngest</c> (<c>engine.Receive</c> 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:
+    /// <list type="bullet">
+    /// <item>a DECK card carries its dealt id (the seeded shuffled-deck identity);</item>
+    /// <item>a GENERATED token carries the wire id <c>CreateActualCard</c>/<c>ReplaceReceivedCards</c> stamped on it
+    ///   (M-HC-2 proved reveal seats the wire cardId);</item>
+    /// <item>a CHOICE/Discover token carries the CHOSEN id (M-HC-4c proved the chosen token lands with its true id);</item>
+    /// <item>a COPY/clone token carries the COPIED id (the engine copies the source card at baseIdx).</item>
+    /// </list>
+    /// Same post-resolution zone search + degrade-to-<paramref name="fallback"/> contract as
+    /// <see cref="PlayedCardCost"/>: no engine / no card → <paramref name="fallback"/>, 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.</summary>
+    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;
+    }
+
     /// <summary>The engine-RESOLVED clan of the card whose engine <c>Index</c> == <paramref name="idx"/> on
     /// <paramref name="playerSeat"/> (M-HC-4e), as the int <c>ClanType</c> ordinal prod sends on the
     /// knownList entry (e.g. <c>clan:8</c> in the tk2 capture). Reads <see cref="BattleCardBase.Clan"/>, 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 <c>item.Value.ToString()</c> at NetworkBattleReceiver.cs:2382). The degrade is
     /// LIVE, not dead: a second concurrent battle that loses the single-active-engine gate has <c>_mgr is null</c>
-    /// 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.</para></summary>
+    /// 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.</para></summary>
     public string PlayedCardTribe(bool playerSeat, int idx, string fallback = "0")
     {
         if (_mgr is null) return fallback;