feat(battlenode): emit engine-resolved clan/tribe on knownList entries (M-HC-4e)

Prod always emits clan (int ClanType) + tribe (comma-joined int TribeType
string, "0" for none) on every knownList entry (battle-traffic_tk2_regular
.ndjson). Source both off the resolved engine (SessionBattleEngine.PlayedCardClan/
PlayedCardTribe -> BattleCardBase.Clan/Tribe), so skill-applied clan/tribe
changes ride the wire rather than the static card-master value. Thread through
KnownListBuilder.BuildPlayedCard + PlayActionsHandler; add clan/tribe to the
KnownCardEntry DTO (always present, non-null). Node-side only; no engine edits,
drift clean.

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

SVSim.UnitTests/BattleNode/Integration/CaptureConformanceTests.cs

@@ -294,7 +294,10 @@ public class CaptureConformanceTests
         var ourEntry = ourDoc.RootElement.GetProperty("knownList")[0];
         using var prodDoc = JsonDocument.Parse(prodEntry);
 
-        // We are responsible for idx/cardId/to (+ spellboost/attachTarget). cost/clan/tribe are deferred.
+        // This is a pure-BUILDER shape check: idx/cardId/to are synthesized here; cost/clan/tribe are
+        // ENGINE-sourced at the handler (PlayActionsHandler reads them off the resolved engine and passes them
+        // to BuildPlayedCard — covered by HeadlessConductorTests), so this builder-only call leaves them at
+        // their defaults and we assert only the structural keys.
         foreach (var key in new[] { "idx", "cardId", "to" })
         {
             Assert.That(ourEntry.TryGetProperty(key, out var ours), Is.True, $"knownList entry missing '{key}'");
@@ -342,7 +345,8 @@ public class CaptureConformanceTests
         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).
+        // Pure-BUILDER shape check: idx/cardId/to are synthesized here; cost/clan/tribe are ENGINE-sourced at
+        // the handler (covered by HeadlessConductorTests), so this builder-only call leaves them at defaults.
         foreach (var key in new[] { "idx", "cardId", "to" })
         {
             Assert.That(ourEntry.TryGetProperty(key, out var ours), Is.True, $"knownList entry missing '{key}'");
@@ -424,7 +428,8 @@ public class CaptureConformanceTests
         // keyAction is {type,cardId} only (selectCard stripped for the hidden open:0 choice); knownList
         // reveals the generating DECK card. The choiceAdd lands a hidden token at idx 46 (candidates).
         // Subset check covers playIdx/type/keyAction — the parts we own; knownList idx/cardId/to are
-        // asserted explicitly below (cost/clan/tribe are deferred, re-derived by the receiver from cardId).
+        // asserted explicitly below (cost/clan/tribe are ENGINE-sourced at the handler, covered by
+        // HeadlessConductorTests, so this builder-only call leaves them at defaults — not checked here).
         const string prodFrame = """
         { "playIdx": 18, "type": 30,
           "keyAction": [ { "type": 1, "cardId": 810014030 } ] }
@@ -471,8 +476,8 @@ public class CaptureConformanceTests
         Assert.That(ourKa.GetProperty("cardId").GetInt64(), Is.EqualTo(810014030L));
 
         // The generating deck card reveals on its own play (idx 18 -> 810014030, to 30). cost/clan/tribe
-        // are deferred (receiver re-derives from cardId), so only idx/cardId/to are checked — as in the
-        // sibling SynthesizedKnownList_* tests.
+        // are ENGINE-sourced at the handler (covered by HeadlessConductorTests); this builder-only call
+        // leaves them at defaults, so only idx/cardId/to are checked — as in the sibling SynthesizedKnownList_* tests.
         var ourKnown = ourDoc.RootElement.GetProperty("knownList")[0];
         Assert.That(ourKnown.GetProperty("idx").GetInt32(), Is.EqualTo(18));
         Assert.That(ourKnown.GetProperty("cardId").GetInt64(), Is.EqualTo(810014030L));

SVSim.UnitTests/BattleNode/Integration/HeadlessConductorTests.cs

@@ -1,6 +1,7 @@
 using System.Collections.Generic;
 using System.Linq;
 using NUnit.Framework;
+using SVSim.BattleNode.Bridge;
 using SVSim.BattleNode.Protocol;
 using SVSim.BattleNode.Protocol.Bodies;
 using SVSim.BattleNode.Sessions;
@@ -1168,6 +1169,122 @@ public class HeadlessConductorTests
             "non-vacuity: the emitted cost must NOT be the un-reduced base cost (6)");
     }
 
+    // === M-HC-4e: engine-resolved clan/tribe on the knownList =====================================
+    //
+    // Prod ALWAYS emits clan (int ClanType ordinal) + tribe (comma-joined int TribeType string, "0" for
+    // none) on every knownList entry (battle-traffic_tk2_regular.ndjson, e.g.
+    // {idx:17,cardId:128821011,...,clan:8,tribe:"7,16",...}). The node now sources both off the resolved
+    // engine (SessionBattleEngine.PlayedCardClan/PlayedCardTribe → BattleCardBase.Clan/Tribe), so a
+    // skill-applied clan/tribe change rides the wire. The fixture 900231030 (ROYAL/clan 2, LEGION/tribe "2",
+    // cost 0) gives concrete non-zero values so the assertion is non-vacuous (NOT the 0/"0" no-tribe default).
+    private const long ClanTribeFollowerId = NodeNativeBattleHarness.ClanTribeFollowerId;     // 900231030
+    private const int ClanTribeFollowerClan = NodeNativeBattleHarness.ClanTribeFollowerClan;  // 2 (ROYAL)
+    private const string ClanTribeFollowerTribe = NodeNativeBattleHarness.ClanTribeFollowerTribe; // "2" (LEGION)
+
+    [Test]
+    public void PlayedCardClan_and_Tribe_read_engine_resolved_values()
+    {
+        // Engine-read proof (mirrors PlayedCardCost_*): drive a node-native battle under a Swordcraft (clan 2)
+        // seat A — so the ROYAL fixture is legal — play the cost-0 fixture turn 1, then read clan/tribe off the
+        // resolved engine by the played card's engine Index. They must be the engine's LIVE values (clan 2,
+        // tribe "2"), in the exact prod wire form.
+        using var harness = NodeNativeBattleHarness.Create(
+            seatADeck: NodeNativeBattleHarness.ClanTribeDeck(), seatAClass: CardClass.Swordcraft);
+
+        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 handIdx = FindHandIdxByCardId(harness, ClanTribeFollowerId);
+        Assert.That(handIdx, Is.GreaterThan(0), "the clan/tribe fixture must be in seat A's opening hand");
+        Assert.That(harness.Push(NetworkBattleUri.PlayActions, PlayBody(handIdx), isPlayerSeat: true).Accepted,
+            Is.True, "cost-0 fixture play ingest");
+
+        // The PAYOFF reads: clan/tribe off the resolved engine, in the prod wire form.
+        Assert.That(harness.Engine.PlayedCardClan(playerSeat: true, handIdx, fallback: -1),
+            Is.EqualTo(ClanTribeFollowerClan),
+            "PlayedCardClan must equal the engine-resolved clan (ROYAL == 2)");
+        Assert.That(harness.Engine.PlayedCardTribe(playerSeat: true, handIdx),
+            Is.EqualTo(ClanTribeFollowerTribe),
+            "PlayedCardTribe must equal the engine-resolved tribe in prod wire form (LEGION == \"2\")");
+    }
+
+    [Test]
+    public void PlayedCardTribe_is_zero_string_for_a_no_tribe_card()
+    {
+        // The no-tribe form: prod sends tribe "0" (== TribeType.ALL == 0), never empty/omitted. The default
+        // vanilla follower (VanillaFollowerId) carries no tribe, so its engine-resolved tribe must render "0".
+        using var harness = NodeNativeBattleHarness.Create();
+
+        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 vanillaHandIdx = FindHandIdxByCardId(harness, NodeNativeBattleHarness.VanillaFollowerId);
+        Assert.That(vanillaHandIdx, Is.GreaterThan(0), "a vanilla follower must be in seat A's opening hand");
+        Assert.That(harness.Push(NetworkBattleUri.PlayActions, PlayBody(vanillaHandIdx), isPlayerSeat: true).Accepted,
+            Is.True, "vanilla play ingest");
+
+        Assert.That(harness.Engine.PlayedCardTribe(playerSeat: true, vanillaHandIdx), Is.EqualTo("0"),
+            "a no-tribe card's wire tribe is the single \"0\" (TribeType.ALL), never empty");
+    }
+
+    [Test]
+    public void Handler_emits_engine_resolved_clan_and_tribe_on_knownList()
+    {
+        // The end-to-end payoff (mirrors Handler_emits_engine_resolved_cost_on_knownList): play the clan/tribe
+        // fixture, INGEST it (engine resolves the play), then run PlayActionsHandler.Handle and inspect the
+        // emitted knownList[0].clan/.tribe. They must equal the engine-resolved values (clan 2, tribe "2") —
+        // proving clan/tribe reach the opponent-facing wire engine-sourced, matching the prod form.
+        using var harness = NodeNativeBattleHarness.Create(
+            seatADeck: NodeNativeBattleHarness.ClanTribeDeck(), seatAClass: CardClass.Swordcraft);
+
+        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 handIdx = FindHandIdxByCardId(harness, ClanTribeFollowerId);
+        Assert.That(handIdx, Is.GreaterThan(0), "the clan/tribe fixture must be in seat A's opening hand");
+
+        var playBody = HandlerPlayBody(handIdx);
+        Assert.That(harness.Push(NetworkBattleUri.PlayActions, playBody, isPlayerSeat: true).Accepted,
+            Is.True, "fixture play ingest");
+
+        harness.SeatA.Phase = HandshakePhase.AfterReady;
+        harness.SeatB.Phase = HandshakePhase.AfterReady;
+        var env = new MsgEnvelope(
+            NetworkBattleUri.PlayActions, ViewerId: harness.SeatA.ViewerId, Uuid: "udid-test", Bid: null,
+            RetryAttempt: 0, Cat: EmitCategory.Battle, PubSeq: null, PlaySeq: null,
+            Body: new RawBody(playBody));
+        var ctx = new FrameDispatchContext
+        {
+            A = harness.SeatA, B = harness.SeatB, From = harness.SeatA, Other = harness.SeatB,
+            Env = env, BattleId = "test-battle", State = harness.State, Engine = harness.Engine,
+        };
+
+        var routes = new PlayActionsHandler().Handle(ctx);
+
+        Assert.That(routes, Has.Count.EqualTo(1), "one route to the opponent");
+        var body = routes[0].Frame.Body as PlayActionsBroadcastBody;
+        Assert.That(body, Is.Not.Null, "frame body is a PlayActionsBroadcastBody");
+        Assert.That(body!.KnownList, Is.Not.Null.And.Count.EqualTo(1), "one knownList entry (the played fixture)");
+        Assert.That(body.KnownList![0].CardId, Is.EqualTo(ClanTribeFollowerId), "the fixture's identity");
+        // THE assertions: clan/tribe are the engine-resolved values, in the prod wire form.
+        Assert.That(body.KnownList[0].Clan, Is.EqualTo(ClanTribeFollowerClan),
+            "knownList[].clan must be the engine-resolved clan ordinal (ROYAL == 2)");
+        Assert.That(body.KnownList[0].Tribe, Is.EqualTo(ClanTribeFollowerTribe),
+            "knownList[].tribe must be the engine-resolved tribe in prod wire form (LEGION == \"2\")");
+        // Non-vacuity: the emitted values must NOT be the 0/"0" no-clan/no-tribe default.
+        Assert.That(body.KnownList[0].Clan, Is.Not.EqualTo(0), "non-vacuity: clan must not be the 0 default");
+        Assert.That(body.KnownList[0].Tribe, Is.Not.EqualTo("0"), "non-vacuity: tribe must not be the \"0\" default");
+    }
+
     // 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)

SVSim.UnitTests/BattleNode/Integration/NodeNativeBattleHarness.cs

@@ -132,6 +132,24 @@ internal sealed class NodeNativeBattleHarness : IDisposable
     /// followers evolved (a SET, not an add) — exactly 1.</summary>
     public const int BoardDependentCostReduced = 1;
 
+    /// <summary>A non-trivial CLAN+TRIBE fixture follower (M-HC-4e). cards.json id 900231030: char_type 1
+    /// (follower), clan 2 (ROYAL / Swordcraft), tribe 2 (LEGION), cost 0, 2/2. Cost 0 makes it playable on
+    /// turn-1 PP 1; its clan (2) matches <see cref="CardClass.Swordcraft"/> so it is legal under a Swordcraft
+    /// seat. Its clan/tribe (2 / "2") are concretely non-zero so the engine-sourced clan/tribe read +
+    /// knownList emit assert REAL values (not the 0/"0" no-tribe default). Verified against cards.json AND the
+    /// prod wire form (comma-joined int TribeType as string: tribe 2 → "2"). Present + creatable in
+    /// cards.json.</summary>
+    public const long ClanTribeFollowerId = 900231030;
+
+    /// <summary>The engine-resolved clan of <see cref="ClanTribeFollowerId"/> as the wire int (ROYAL ==
+    /// ClanType 2). The M-HC-4e knownList emit asserts <c>clan</c> equals this.</summary>
+    public const int ClanTribeFollowerClan = 2;
+
+    /// <summary>The engine-resolved tribe of <see cref="ClanTribeFollowerId"/> in the EXACT prod wire string
+    /// form (LEGION == TribeType 2 → the single-element comma-join "2"). The M-HC-4e knownList emit asserts
+    /// <c>tribe</c> equals this.</summary>
+    public const string ClanTribeFollowerTribe = "2";
+
     public BattleSessionState State { get; }
     public StubParticipant SeatA { get; }
     public StubParticipant SeatB { get; }
@@ -176,6 +194,12 @@ internal sealed class NodeNativeBattleHarness : IDisposable
         return deck;
     }
 
+    /// <summary>A 30-card deck of the <see cref="ClanTribeFollowerId"/> clan+tribe fixture (M-HC-4e). All one
+    /// identity, all cost 0 — so the opening hand reliably holds a copy to play turn 1, regardless of shuffle,
+    /// and the engine-resolved clan/tribe read off the played card is unambiguous.</summary>
+    public static IReadOnlyList<long> ClanTribeDeck() =>
+        Enumerable.Repeat(ClanTribeFollowerId, 30).ToList();
+
     /// <summary>Seat the engine exactly as <c>BattleSession.EnsureEngineSetup</c> does: shuffle each
     /// side's deck from the fixed seed via <see cref="BattleSessionState.GetShuffledDeck"/>, then
     /// <c>SessionBattleEngine.Setup(seed, deckA, deckB, classA, classB)</c>.</summary>