feat(eval): add count-aware threat GAM

The incumbent threat table cannot distinguish repeated high-order threat counts without widening the consumed V2a joint surface. Add zero-referenced count and pair residuals beside the unchanged 11-bit table, with fail-closed v8 loading and deterministic support isolation.

Extend tuner export, parity, and fixed-scale evaluation support for the new component. Consume exact tail batches only for ThreatGam so the new recipe receives its frozen dose while pinned legacy replay retains full-batch-only optimizer semantics.

Author: dhbloo

Rapfi/command/tuning.cpp

@@ -31,6 +31,7 @@
 #include "search/searcher.h"
 #include "search/searchthread.h"
 
+#include <algorithm>
 #include <array>
 #include <cpptoml.h>
 #include <cstdint>
@@ -58,20 +59,60 @@ constexpr uint32_t I(uint32_t y, uint32_t x)
 constexpr std::array<char, 8> ClassicalModelExtensionMagic =
     {'R', 'F', 'C', 'L', 'M', 'O', 'D', '1'};
 constexpr uint32_t ClassicalModelCompactP3Version = 7;
+constexpr uint32_t ClassicalModelThreatGamVersion = 8;
 constexpr uint32_t ModelPolicyTableCount          = 1;
 constexpr uint32_t ModelPolicyContextCount        = Evaluation::PolicyStoredContextCount;
 constexpr uint32_t ModelBlendComponentCount       = 0;
 constexpr uint32_t PolicyCrossPatternCount        = Evaluation::PolicyStoredPatternCount;
 constexpr uint32_t PolicyCrossPayloadBytes =
     ModelPolicyContextCount * PolicyCrossPatternCount * PolicyCrossPatternCount * sizeof(Score);
 constexpr uint32_t ClassicalModelCompactP3PayloadBytes = PolicyCrossPayloadBytes;
+constexpr uint32_t ThreatGamExtraPayloadBytes =
+    (RULE_NB + 1)
+    * (ThreatGamAxisCount * ThreatGamLevelCount
+       + ThreatGamPairCount * ThreatGamLevelCount * ThreatGamLevelCount)
+    * sizeof(Eval);
 
 static_assert(ModelPolicyContextCount == Search::QUIET);
 static_assert(Search::QUIET + 1 == Search::POLICY_CONTEXT_NB);
 static_assert(ModelPolicyContextCount < Evaluation::PolicyContextCount);
 
 using StoredPolicyCross =
     Score[ModelPolicyContextCount][PolicyCrossPatternCount][PolicyCrossPatternCount];
+using StoredThreatGamCount = Eval[RULE_NB + 1][ThreatGamAxisCount][ThreatGamLevelCount];
+using StoredThreatGamPair =
+    Eval[RULE_NB + 1][ThreatGamPairCount][ThreatGamLevelCount][ThreatGamLevelCount];
+
+bool hasValidThreatGamReferences(const StoredThreatGamCount &count, const StoredThreatGamPair &pair)
+{
+    for (size_t table = 0; table < RULE_NB + 1; table++) {
+        for (size_t axis = 0; axis < ThreatGamAxisCount; axis++)
+            if (count[table][axis][0] != 0 || count[table][axis][1] != 0)
+                return false;
+        for (size_t p = 0; p < ThreatGamPairCount; p++)
+            for (size_t lhs = 0; lhs < ThreatGamLevelCount; lhs++)
+                for (size_t rhs = 0; rhs < ThreatGamLevelCount; rhs++)
+                    if ((lhs < 2 || rhs < 2) && pair[table][p][lhs][rhs] != 0)
+                        return false;
+    }
+    return true;
+}
+
+bool hasThreatGamValues(const StoredThreatGamCount &count, const StoredThreatGamPair &pair)
+{
+    for (const auto &table : count)
+        for (const auto &axis : table)
+            for (Eval value : axis)
+                if (value != 0)
+                    return true;
+    for (const auto &table : pair)
+        for (const auto &p : table)
+            for (const auto &row : p)
+                for (Eval value : row)
+                    if (value != 0)
+                        return true;
+    return false;
+}
 
 }  // namespace
 
@@ -84,13 +125,38 @@ float ScalingFactor = 200.0f;
 // Classical evaluation and score tables
 // Note that Renju has asymmetry eval and score
 
-Eval          EVALS[RULE_NB + 1][PCODE_NB];
-Eval          EVALS_THREAT[RULE_NB + 1][THREAT_NB];
+Eval EVALS[RULE_NB + 1][PCODE_NB];
+Eval EVALS_THREAT[RULE_NB + 1][THREAT_NB];
+Eval THREAT_GAM_COUNT[RULE_NB + 1][ThreatGamAxisCount][ThreatGamLevelCount] = {};
+Eval THREAT_GAM_PAIR[RULE_NB + 1][ThreatGamPairCount][ThreatGamLevelCount][ThreatGamLevelCount] =
+    {};
+bool          THREAT_GAM_ACTIVE[RULE_NB + 1] = {};
 MoveScorePair P4SCORES[RULE_NB + 1][PCODE_NB];
 Score         POLICY_CROSS[RULE_NB + 1][PolicyContextCount][PATTERN4_NB][PATTERN4_NB];
 uint8_t       POLICY_CROSS_ACTIVE_MASK[RULE_NB + 1] = {};
 bool          POLICY_CROSS_PRESENT                  = false;
 
+void resetThreatGam()
+{
+    std::memset(THREAT_GAM_COUNT, 0, sizeof(THREAT_GAM_COUNT));
+    std::memset(THREAT_GAM_PAIR, 0, sizeof(THREAT_GAM_PAIR));
+    std::memset(THREAT_GAM_ACTIVE, 0, sizeof(THREAT_GAM_ACTIVE));
+}
+
+void refreshThreatGamActivation()
+{
+    for (size_t table = 0; table < RULE_NB + 1; table++) {
+        THREAT_GAM_ACTIVE[table] = false;
+        for (const auto &axis : THREAT_GAM_COUNT[table])
+            for (Eval value : axis)
+                THREAT_GAM_ACTIVE[table] |= value != 0;
+        for (const auto &pair : THREAT_GAM_PAIR[table])
+            for (const auto &row : pair)
+                for (Eval value : row)
+                    THREAT_GAM_ACTIVE[table] |= value != 0;
+    }
+}
+
 void resetPolicyCross()
 {
     std::memset(POLICY_CROSS, 0, sizeof(POLICY_CROSS));
@@ -270,7 +336,7 @@ void Config::readRequirement(const cpptoml::table &t)
 {
     auto [major, minor, revision] = getVersionNumbers();
     uint64_t rapVer = ((uint64_t)major << 32) | ((uint64_t)minor << 16) | (uint64_t)revision;
-    auto composeVersion = [](const std::vector<int64_t> &ver, const char *key) {
+    auto     composeVersion = [](const std::vector<int64_t> &ver, const char *key) {
         if (ver.size() != 3)
             throw std::runtime_error(std::string("illegal ") + key);
         for (int64_t component : ver)
@@ -480,6 +546,7 @@ void Config::readModel(const cpptoml::table &t, PendingConfig &pending)
         // extensions. Do not let rows from a previously loaded binary model leak
         // across an in-process config reload.
         Evaluation::resetPolicyCross();
+        Evaluation::resetThreatGam();
         std::memset(Evaluation::EVALS_THREAT, 0, sizeof(Evaluation::EVALS_THREAT));
 
         // Read Eval & Score
@@ -854,22 +921,35 @@ bool Config::loadModel(std::istream &inStream)
     // Decode the whole payload into local staging buffers and publish to the
     // live tables only after every check has passed, so a truncated or corrupt
     // model file leaves the current evaluation state untouched.
-    double scalingFactorF64;
-    Eval   evals[RULE_NB + 1][PCODE_NB];
-    Eval   evalsThreat[RULE_NB + 1][THREAT_NB];
-    Score  scores[RULE_NB + 1][PCODE_NB][2];
+    double               scalingFactorF64;
+    Eval                 evals[RULE_NB + 1][PCODE_NB];
+    Eval                 evalsThreat[RULE_NB + 1][THREAT_NB];
+    Score                scores[RULE_NB + 1][PCODE_NB][2];
+    StoredThreatGamCount threatGamCount {};
+    StoredThreatGamPair  threatGamPair {};
     in->read(reinterpret_cast<char *>(&scalingFactorF64), sizeof(scalingFactorF64));
     in->read(reinterpret_cast<char *>(evals), sizeof(evals));
     in->read(reinterpret_cast<char *>(evalsThreat), sizeof(evalsThreat));
     in->read(reinterpret_cast<char *>(scores), sizeof(scores));
 
     if (!*in)
         return false;
+    float scalingFactor = static_cast<float>(scalingFactorF64);
+    if (!std::isfinite(scalingFactorF64) || scalingFactorF64 <= 0.0 || !std::isfinite(scalingFactor)
+        || scalingFactor <= 0.0f)
+        return false;
 
     auto publishBaseTables = [&]() {
-        Evaluation::ScalingFactor = scalingFactorF64;
+        Evaluation::ScalingFactor = scalingFactor;
         std::memcpy(Evaluation::EVALS, evals, sizeof(Evaluation::EVALS));
         std::memcpy(Evaluation::EVALS_THREAT, evalsThreat, sizeof(Evaluation::EVALS_THREAT));
+        std::memcpy(Evaluation::THREAT_GAM_COUNT,
+                    threatGamCount,
+                    sizeof(Evaluation::THREAT_GAM_COUNT));
+        std::memcpy(Evaluation::THREAT_GAM_PAIR,
+                    threatGamPair,
+                    sizeof(Evaluation::THREAT_GAM_PAIR));
+        Evaluation::refreshThreatGamActivation();
 
         // Set score table to P4SCORES
         for (int rule = 0; rule < RULE_NB + 1; rule++)
@@ -898,29 +978,56 @@ bool Config::loadModel(std::istream &inStream)
     in->read(reinterpret_cast<char *>(&contextCount), sizeof(contextCount));
     in->read(reinterpret_cast<char *>(&componentCount), sizeof(componentCount));
     in->read(reinterpret_cast<char *>(&patternCount), sizeof(patternCount));
-    if (!*in || magic != ClassicalModelExtensionMagic || version != ClassicalModelCompactP3Version
-        || payloadBytes != ClassicalModelCompactP3PayloadBytes
-        || tableCount != ModelPolicyTableCount || contextCount != ModelPolicyContextCount
-        || componentCount != ModelBlendComponentCount || patternCount != PolicyCrossPatternCount)
+    if (!*in || magic != ClassicalModelExtensionMagic)
         return false;
 
-    StoredPolicyCross policyCross;
-    in->read(reinterpret_cast<char *>(policyCross), sizeof(policyCross));
-    if (!*in)
+    bool              hasPolicyCross = false;
+    StoredPolicyCross policyCross {};
+    if (version == ClassicalModelCompactP3Version) {
+        if (payloadBytes != ClassicalModelCompactP3PayloadBytes
+            || tableCount != ModelPolicyTableCount || contextCount != ModelPolicyContextCount
+            || componentCount != ModelBlendComponentCount
+            || patternCount != PolicyCrossPatternCount)
+            return false;
+        in->read(reinterpret_cast<char *>(policyCross), sizeof(policyCross));
+        hasPolicyCross = true;
+    }
+    else if (version == ClassicalModelThreatGamVersion) {
+        bool     validPolicyHeader = tableCount == 0 ? contextCount == 0 && patternCount == 0
+                                                     : tableCount == ModelPolicyTableCount
+                                                       && contextCount == ModelPolicyContextCount
+                                                       && patternCount == PolicyCrossPatternCount;
+        uint32_t expectedPayloadBytes =
+            ThreatGamExtraPayloadBytes + (tableCount ? PolicyCrossPayloadBytes : 0);
+        if (!validPolicyHeader || componentCount != ModelBlendComponentCount
+            || payloadBytes != expectedPayloadBytes)
+            return false;
+        if (tableCount) {
+            in->read(reinterpret_cast<char *>(policyCross), sizeof(policyCross));
+            hasPolicyCross = true;
+        }
+        in->read(reinterpret_cast<char *>(threatGamCount), sizeof(threatGamCount));
+        in->read(reinterpret_cast<char *>(threatGamPair), sizeof(threatGamPair));
+        if (!hasValidThreatGamReferences(threatGamCount, threatGamPair))
+            return false;
+    }
+    else
         return false;
 
-    if (in->peek() != std::ios::traits_type::eof() || in->bad())
+    if (!*in || in->peek() != std::ios::traits_type::eof() || in->bad())
         return false;
     publishBaseTables();
     Evaluation::resetPolicyCross();
-    for (size_t context = 0; context < ModelPolicyContextCount; context++)
-        for (size_t self = 0; self < PolicyCrossPatternCount; self++)
-            for (size_t opponent = 0; opponent < PolicyCrossPatternCount; opponent++)
-                Evaluation::POLICY_CROSS[FREESTYLE][context]
-                                        [Evaluation::policyPatternFromStorageIndex(self)]
-                                        [Evaluation::policyPatternFromStorageIndex(opponent)] =
-                                            policyCross[context][self][opponent];
-    Evaluation::activatePolicyCross();
+    if (hasPolicyCross) {
+        for (size_t context = 0; context < ModelPolicyContextCount; context++)
+            for (size_t self = 0; self < PolicyCrossPatternCount; self++)
+                for (size_t opponent = 0; opponent < PolicyCrossPatternCount; opponent++)
+                    Evaluation::POLICY_CROSS[FREESTYLE][context]
+                                            [Evaluation::policyPatternFromStorageIndex(self)]
+                                            [Evaluation::policyPatternFromStorageIndex(opponent)] =
+                                                policyCross[context][self][opponent];
+        Evaluation::activatePolicyCross();
+    }
     return true;
 }
 
@@ -949,29 +1056,45 @@ void Config::exportModel(std::ostream &outStream)
 
     bool writePolicyCross =
         Evaluation::isPolicyCrossPresent() || !Evaluation::hasDefaultPolicyCross();
-    if (!writePolicyCross)
+    bool writeThreatGam =
+        hasThreatGamValues(Evaluation::THREAT_GAM_COUNT, Evaluation::THREAT_GAM_PAIR);
+    if (!writePolicyCross && !writeThreatGam)
         return;
     out->write(ClassicalModelExtensionMagic.data(), ClassicalModelExtensionMagic.size());
-    uint32_t version        = ClassicalModelCompactP3Version;
-    uint32_t payloadBytes   = ClassicalModelCompactP3PayloadBytes;
-    uint32_t tableCount     = ModelPolicyTableCount;
-    uint32_t contextCount   = ModelPolicyContextCount;
+    uint32_t version =
+        writeThreatGam ? ClassicalModelThreatGamVersion : ClassicalModelCompactP3Version;
+    uint32_t payloadBytes   = writeThreatGam ? ThreatGamExtraPayloadBytes
+                                                 + (writePolicyCross ? PolicyCrossPayloadBytes : 0)
+                                             : ClassicalModelCompactP3PayloadBytes;
+    uint32_t tableCount     = writePolicyCross ? ModelPolicyTableCount : 0;
+    uint32_t contextCount   = writePolicyCross ? ModelPolicyContextCount : 0;
     uint32_t componentCount = ModelBlendComponentCount;
-    uint32_t patternCount   = PolicyCrossPatternCount;
+    uint32_t patternCount   = writePolicyCross ? PolicyCrossPatternCount : 0;
     out->write(reinterpret_cast<const char *>(&version), sizeof(version));
     out->write(reinterpret_cast<const char *>(&payloadBytes), sizeof(payloadBytes));
     out->write(reinterpret_cast<const char *>(&tableCount), sizeof(tableCount));
     out->write(reinterpret_cast<const char *>(&contextCount), sizeof(contextCount));
     out->write(reinterpret_cast<const char *>(&componentCount), sizeof(componentCount));
     out->write(reinterpret_cast<const char *>(&patternCount), sizeof(patternCount));
 
-    StoredPolicyCross policyCross;
-    for (size_t context = 0; context < ModelPolicyContextCount; context++)
-        for (size_t self = 0; self < PolicyCrossPatternCount; self++)
-            for (size_t opponent = 0; opponent < PolicyCrossPatternCount; opponent++)
-                policyCross[context][self][opponent] =
-                    Evaluation::POLICY_CROSS[FREESTYLE][context]
-                                            [Evaluation::policyPatternFromStorageIndex(self)]
-                                            [Evaluation::policyPatternFromStorageIndex(opponent)];
-    out->write(reinterpret_cast<const char *>(policyCross), sizeof(policyCross));
+    if (writePolicyCross) {
+        StoredPolicyCross policyCross;
+        for (size_t context = 0; context < ModelPolicyContextCount; context++)
+            for (size_t self = 0; self < PolicyCrossPatternCount; self++)
+                for (size_t opponent = 0; opponent < PolicyCrossPatternCount; opponent++)
+                    policyCross[context][self][opponent] =
+                        Evaluation::POLICY_CROSS[FREESTYLE][context]
+                                                [Evaluation::policyPatternFromStorageIndex(self)]
+                                                [Evaluation::policyPatternFromStorageIndex(
+                                                    opponent)];
+        out->write(reinterpret_cast<const char *>(policyCross), sizeof(policyCross));
+    }
+    if (writeThreatGam) {
+        if (!hasValidThreatGamReferences(Evaluation::THREAT_GAM_COUNT, Evaluation::THREAT_GAM_PAIR))
+            throw std::runtime_error("threat GAM reference cells must remain zero");
+        out->write(reinterpret_cast<const char *>(Evaluation::THREAT_GAM_COUNT),
+                   sizeof(Evaluation::THREAT_GAM_COUNT));
+        out->write(reinterpret_cast<const char *>(Evaluation::THREAT_GAM_PAIR),
+                   sizeof(Evaluation::THREAT_GAM_PAIR));
+    }
 }

Rapfi/config.cpp

@@ -29,6 +29,20 @@ using Evaluation::EvalCfg;
 
 namespace {
 
+constexpr uint8_t quantizeThreatCount(uint16_t count)
+{
+    return static_cast<uint8_t>(count < 3 ? count : 3);
+}
+
+std::array<uint8_t, ThreatGamAxisCount> makeThreatCounts(const StateInfo &st, Color self)
+{
+    Color oppo = ~self;
+    return {quantizeThreatCount(st.p4Count[oppo][E_BLOCK4]),
+            quantizeThreatCount(st.p4Count[oppo][H_FLEX3]),
+            quantizeThreatCount(st.p4Count[self][H_FLEX3]),
+            quantizeThreatCount(st.p4Count[self][E_BLOCK4])};
+}
+
 /// Makes threat mask according current pattern4 counts on board.
 int makeThreatMask(const StateInfo &st, Color self)
 {
@@ -58,7 +72,6 @@ int makeThreatMask(const StateInfo &st, Color self)
     mask |= 0b100000000 & -int(oppoFour);
     mask |= 0b1000000000 & -int(oppoThreePlus);
     mask |= 0b10000000000 & -int(oppoThree);
-
     assert(0 <= mask && mask < THREAT_NB);
     return mask;
 }
@@ -68,8 +81,18 @@ int makeThreatMask(const StateInfo &st, Color self)
 template <Rule R>
 inline Value evaluateThreat(const StateInfo &st, Color self)
 {
-    return (
-        Value)Evaluation::EVALS_THREAT[Evaluation::tableIndex(R, self)][makeThreatMask(st, self)];
+    const size_t table = Evaluation::tableIndex(R, self);
+    int          value = Evaluation::EVALS_THREAT[table][makeThreatMask(st, self)];
+    if (Evaluation::THREAT_GAM_ACTIVE[table]) {
+        auto counts = makeThreatCounts(st, self);
+        for (size_t axis = 0; axis < ThreatGamAxisCount; axis++)
+            value += Evaluation::THREAT_GAM_COUNT[table][axis][counts[axis]];
+        for (size_t pair = 0; pair < ThreatGamPairCount; pair++) {
+            auto [lhs, rhs] = ThreatGamPairs[pair];
+            value += Evaluation::THREAT_GAM_PAIR[table][pair][counts[lhs]][counts[rhs]];
+        }
+    }
+    return static_cast<Value>(value);
 }
 
 /// Evaluates basic patterns on board.
@@ -171,6 +194,7 @@ EvalInfo::EvalInfo(const Board &board, Rule rule)
     : plyBack {0}
     , self(board.sideToMove())
     , threatMask(makeThreatMask(board.stateInfo(), self))
+    , threatCounts(makeThreatCounts(board.stateInfo(), self))
 {
     Board &b = const_cast<Board &>(board);
     Pos    undoHistory[2];

Rapfi/eval/eval.cpp

@@ -21,6 +21,8 @@
 #include "../core/types.h"
 #include "scoretables.h"
 
+#include <array>
+
 class Board;
 
 namespace Evaluation {
@@ -39,8 +41,9 @@ struct EvalInfo
     {
         uint16_t pcodeCount[SIDE_NB][PCODE_NB];
     } plyBack[2];
-    Color self;
-    int   threatMask;
+    Color                                   self;
+    int                                     threatMask;
+    std::array<uint8_t, ThreatGamAxisCount> threatCounts;
 
     EvalInfo(const Board &board, Rule rule);
 };