cover unlock state in the determinism tests

The scripted session only placed buildings, so every unlock container stayed at
its initial value for the whole run and the checksum never saw them change. It
now destroys the enemy stations twice and takes the offered schematic choice,
so awarded groups, per-schematic levels and the derived recipe/item sets are
exercised too.

Adds a test that pins down that unlock state actually reaches the checksum: two
sessions in lockstep, one takes the choice, checksums must diverge. The
scripted-session tests cannot show this themselves — they compare runs against
each other, so they pass whether or not UnlockState is in the fold. Verified by
temporarily removing the fold: the new test fails, the old two do not.

The first choice is asserted rather than assumed, so a config change that stops
offering a group fails loudly instead of silently dropping the coverage.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YHcUerKAZKWNvSKJxYKbnG

src/lib/sim/CMakeLists.txt

@@ -19,6 +19,7 @@ SET(HDRS
     ${CMAKE_CURRENT_SOURCE_DIR}/ShipStatsCalculator.h
     ${CMAKE_CURRENT_SOURCE_DIR}/StateChecksum.h
     ${CMAKE_CURRENT_SOURCE_DIR}/ThreatCostCalculator.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/UnlockState.h
     ${CMAKE_CURRENT_SOURCE_DIR}/WaveSystem.h
     PARENT_SCOPE
 )
@@ -40,6 +41,7 @@ SET(SRCS
     ${CMAKE_CURRENT_SOURCE_DIR}/ShipStatsCalculator.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/StateChecksum.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/ThreatCostCalculator.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/UnlockState.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/WaveSystem.cpp
     PARENT_SCOPE
 )

src/lib/sim/Simulation.cpp

@@ -6,7 +6,6 @@
 
 #include "AiSystem.h"
 #include "Command.h"
-#include "DisplayName.h"
 #include "BuildingSystem.h"
 #include "CombatSystem.h"
 #include "DynamicBodyComponent.h"
@@ -43,6 +42,7 @@ Simulation::Simulation(GameConfig config, unsigned int seed)
     , m_hqProxyEntity(entt::null)
     , m_playerStation1Entity(entt::null)
     , m_playerStation2Entity(entt::null)
+    , m_unlockState(m_config)
     , m_beltSystem(m_config.world.beltSpeed_tps)
 {
     m_currentEnemyStationEntities[0] = entt::null;
@@ -50,7 +50,7 @@ Simulation::Simulation(GameConfig config, unsigned int seed)
 
     initializeSubsystems();
 
-    initializeUnlockState();
+    m_unlockState.initializeUnlockState();
     placeInitialStructures();
 	registerForEvents();
 }
@@ -97,7 +97,7 @@ void Simulation::reset(unsigned int seed)
     m_beltSystem = BeltSystem(m_config.world.beltSpeed_tps);
     initializeSubsystems();
 
-    initializeUnlockState();
+    m_unlockState.initializeUnlockState();
     placeInitialStructures();
 }
 
@@ -110,9 +110,7 @@ void Simulation::initializeSubsystems()
         [this](int amount) { m_buildingBlocksStock += amount; },
         [this](const std::string& id, QVector2D pos,
                const std::optional<ShipLayoutConfig>& layout) {
-            const std::map<std::string, SchematicState>::const_iterator it =
-                m_schematicLevels.find(id);
-            if (it == m_schematicLevels.end() || !it->second.unlocked)
+            if (!isSchematicUnlocked(id))
             {
                 return;
             }
@@ -131,55 +129,6 @@ void Simulation::initializeSubsystems()
     m_combatSystem   = std::make_unique<CombatSystem>(m_config);
 }
 
-void Simulation::initializeUnlockState()
-{
-    // Cache the ids granted by some unlock group (REQ-LOCK-EXPLICIT); an item
-    // starts locked iff it is granted by a group.
-    m_grantedShipIds.clear();
-    m_grantedModuleIds.clear();
-    m_grantedBuildingIds.clear();
-    m_grantedRecipeIds.clear();
-    for (const UnlockGroupDef& group : m_config.unlocks.groups)
-    {
-        m_grantedShipIds.insert(group.ships.begin(), group.ships.end());
-        m_grantedModuleIds.insert(group.modules.begin(), group.modules.end());
-        m_grantedBuildingIds.insert(group.buildings.begin(), group.buildings.end());
-        m_grantedRecipeIds.insert(group.recipes.begin(), group.recipes.end());
-    }
-
-    m_awardedUnlockGroupIds.clear();
-
-    m_schematicLevels.clear();
-    for (const ShipDef& def : m_config.ships.ships)
-    {
-        SchematicState state;
-        state.unlocked = (m_grantedShipIds.count(def.id) == 0);
-        m_schematicLevels[def.id] = state;
-    }
-
-    m_moduleSchematicLevels.clear();
-    for (const ModuleDef& def : m_config.modules.modules)
-    {
-        SchematicState state;
-        state.unlocked = (m_grantedModuleIds.count(def.id) == 0);
-        m_moduleSchematicLevels[def.id] = state;
-    }
-
-    m_buildingLevels.clear();
-    for (const BuildingDef& def : m_config.buildings.buildings)
-    {
-        SchematicState state;
-        state.unlocked = (m_grantedBuildingIds.count(def.id) == 0);
-        m_buildingLevels[def.id] = state;
-    }
-
-    // Gated assembler recipes start locked; unlocked_at_start recipes are handled
-    // in the REQ-LOCK-IMPLICIT traversal, not tracked here.
-    m_unlockedRecipeSchematicIds.clear();
-
-    recomputeUnlocked();
-}
-
 // ---------------------------------------------------------------------------
 // tick
 // ---------------------------------------------------------------------------
@@ -613,9 +562,9 @@ void Simulation::generateSchematicChoices(int destroyedStationLevel)
     std::vector<const UnlockGroupDef*> pool;
     for (const UnlockGroupDef& group : m_config.unlocks.groups)
     {
-        if (m_awardedUnlockGroupIds.count(group.id) > 0) { continue; }
+        if (m_unlockState.isUnlockGroupAwarded(group.id)) { continue; }
         if (group.stationLevel < 0 || group.stationLevel > destroyedStationLevel) { continue; }
-        if (!prerequisitesSatisfied(group.requiredGroupIds)) { continue; }
+        if (!m_unlockState.prerequisitesSatisfied(group.requiredGroupIds)) { continue; }
         pool.push_back(&group);
     }
 
@@ -639,7 +588,7 @@ void Simulation::generateSchematicChoices(int destroyedStationLevel)
         const std::size_t endIdx  = pool.size() - 1 - static_cast<std::size_t>(i);
         std::swap(pool[rollIdx], pool[endIdx]);
 
-        m_pendingSchematicChoices.push_back(makeUnlockOption(*pool[endIdx]));
+        m_pendingSchematicChoices.push_back(m_unlockState.makeUnlockOption(*pool[endIdx]));
     }
 
     if (artifactRolled)
@@ -651,48 +600,6 @@ void Simulation::generateSchematicChoices(int destroyedStationLevel)
     }
 }
 
-SchematicChoiceOption Simulation::makeUnlockOption(const UnlockGroupDef& group) const
-{
-    SchematicChoiceOption option;
-    option.isArtifact    = false;
-    option.unlockGroupId = group.id;
-    option.displayName   = toDisplayName(group.id);
-
-    for (const std::string& id : group.ships)
-    {
-        option.grantedItems.push_back({SchematicType::Ship, id, toDisplayName(id)});
-    }
-    for (const std::string& id : group.modules)
-    {
-        option.grantedItems.push_back({SchematicType::Module, id, toDisplayName(id)});
-    }
-    for (const std::string& id : group.buildings)
-    {
-        option.grantedItems.push_back({SchematicType::Building, id, toDisplayName(id)});
-    }
-    for (const std::string& id : group.recipes)
-    {
-        option.grantedItems.push_back({SchematicType::Recipe, id, toDisplayName(id)});
-    }
-
-    // REQ-DEF-SCHEMATIC-DROP: preview recipes newly implicitly unlocked by
-    // awarding this whole group. Seed the hypothetical explicit-unlock sets with
-    // every grant (ship + module materials via step 1a, recipe outputs via step
-    // 1b), then diff against the current implicit set.
-    std::set<std::string> hypotheticalShipIds            = getUnlockedShipSchematicIds();
-    std::set<std::string> hypotheticalModuleIds          = getUnlockedModuleSchematicIds();
-    std::set<std::string> hypotheticalRecipeSchematicIds = m_unlockedRecipeSchematicIds;
-    for (const std::string& id : group.ships)   { hypotheticalShipIds.insert(id); }
-    for (const std::string& id : group.modules) { hypotheticalModuleIds.insert(id); }
-    for (const std::string& id : group.recipes) { hypotheticalRecipeSchematicIds.insert(id); }
-
-    const UnlockedSets hypothetical = computeUnlockedSets(
-        hypotheticalShipIds, hypotheticalModuleIds, hypotheticalRecipeSchematicIds);
-    option.newlyUnlockedRecipeIds = computeNewlyUnlockedRecipeIds(hypothetical);
-
-    return option;
-}
-
 void Simulation::applySchematicChoice(int choiceIndex)
 {
     assert(choiceIndex >= 0 && choiceIndex < static_cast<int>(m_pendingSchematicChoices.size()));
@@ -709,204 +616,24 @@ void Simulation::applySchematicChoice(int choiceIndex)
         return;
     }
 
-    // Award the whole unlock group (REQ-DEF-SCHEMATIC-DROP): unlock every granted
-    // ship, module, building, and assembler recipe at once.
-    m_awardedUnlockGroupIds.insert(chosen.unlockGroupId);
-    for (const GrantedSchematic& grant : chosen.grantedItems)
-    {
-        switch (grant.type)
-        {
-        case SchematicType::Ship:     m_schematicLevels.at(grant.id).unlocked = true;       break;
-        case SchematicType::Module:   m_moduleSchematicLevels.at(grant.id).unlocked = true; break;
-        case SchematicType::Building: m_buildingLevels.at(grant.id).unlocked = true;        break;
-        case SchematicType::Recipe:   m_unlockedRecipeSchematicIds.insert(grant.id);        break;
-        }
-    }
-
-    recomputeUnlocked();
+    m_unlockState.awardUnlockGroup(chosen);
     m_pendingSchematicChoices.clear();
 }
 
-// ---------------------------------------------------------------------------
-// Implicit unlock computation (REQ-LOCK-IMPLICIT)
-// ---------------------------------------------------------------------------
-
-void Simulation::recomputeUnlocked()
-{
-    const UnlockedSets result = computeUnlockedSets(
-        getUnlockedShipSchematicIds(), getUnlockedModuleSchematicIds(), m_unlockedRecipeSchematicIds);
-    m_unlockedItemIds   = result.itemIds;
-    m_unlockedRecipeIds = result.recipeIds;
-}
-
-std::set<std::string> Simulation::getUnlockedShipSchematicIds() const
-{
-    std::set<std::string> ids;
-    for (const auto& [id, state] : m_schematicLevels)
-    {
-        if (state.unlocked) { ids.insert(id); }
-    }
-    return ids;
-}
-
-std::set<std::string> Simulation::getUnlockedModuleSchematicIds() const
-{
-    std::set<std::string> ids;
-    for (const auto& [id, state] : m_moduleSchematicLevels)
-    {
-        if (state.unlocked) { ids.insert(id); }
-    }
-    return ids;
-}
-
-bool Simulation::prerequisitesSatisfied(const std::vector<std::string>& requiredGroupIds) const
-{
-    // A prerequisite is satisfied only once the named unlock group has been
-    // awarded (REQ-LOCK-PREREQ).
-    for (const std::string& groupId : requiredGroupIds)
-    {
-        if (m_awardedUnlockGroupIds.count(groupId) == 0) { return false; }
-    }
-    return true;
-}
-
-Simulation::UnlockedSets Simulation::computeUnlockedSets(
-    const std::set<std::string>& unlockedShipSchematicIds,
-    const std::set<std::string>& unlockedModuleSchematicIds,
-    const std::set<std::string>& unlockedRecipeSchematicIds) const
-{
-    UnlockedSets result;
-
-    for (const ShipDef& def : m_config.ships.ships)
-    {
-        if (unlockedShipSchematicIds.count(def.id) == 0) { continue; }
-        for (const RecipeIngredient& mat : def.schematic.materials)
-        {
-            result.itemIds.insert(mat.item);
-        }
-    }
-    for (const ModuleDef& def : m_config.modules.modules)
-    {
-        if (unlockedModuleSchematicIds.count(def.id) == 0) { continue; }
-        for (const RecipeIngredient& mat : def.materials)
-        {
-            result.itemIds.insert(mat.item);
-        }
-    }
-    for (const RecipeDef& def : m_config.recipes.recipes)
-    {
-        // An assembler recipe seeds the base set when it is explicitly available:
-        // flagged unlocked_at_start (base recipes the graph can't reach), or a
-        // gated recipe whose unlock group has been awarded (REQ-LOCK-EXPLICIT).
-        if (def.building == BuildingType::Assembler
-            && (def.unlockedAtStart || unlockedRecipeSchematicIds.count(def.id) > 0))
-        {
-            for (const RecipeOutput& out : def.outputs)
-            {
-                result.itemIds.insert(out.item);
-            }
-        }
-    }
-
-    bool changed = true;
-    while (changed)
-    {
-        changed = false;
-        for (const RecipeDef& recipe : m_config.recipes.recipes)
-        {
-            if (recipe.building != BuildingType::Miner
-                && recipe.building != BuildingType::Smelter
-                && recipe.building != BuildingType::Assembler)
-            {
-                continue;
-            }
-            // Skip a gated assembler recipe (granted by an unlock group) whose
-            // group has not yet been awarded (REQ-LOCK-IMPLICIT step 2).
-            if (recipe.building == BuildingType::Assembler
-                && m_grantedRecipeIds.count(recipe.id) > 0
-                && unlockedRecipeSchematicIds.count(recipe.id) == 0)
-            {
-                continue;
-            }
-            bool producesUnlocked = false;
-            for (const RecipeOutput& out : recipe.outputs)
-            {
-                if (result.itemIds.count(out.item) > 0)
-                {
-                    producesUnlocked = true;
-                    break;
-                }
-            }
-            if (!producesUnlocked) { continue; }
-
-            if (recipe.building == BuildingType::Miner
-                || recipe.building == BuildingType::Assembler)
-            {
-                result.recipeIds.insert(recipe.id);
-            }
-            for (const RecipeIngredient& ing : recipe.inputs)
-            {
-                if (result.itemIds.insert(ing.item).second)
-                {
-                    changed = true;
-                }
-            }
-        }
-    }
-
-    return result;
-}
-
-std::vector<std::string> Simulation::computeNewlyUnlockedRecipeIds(const UnlockedSets& hypothetical) const
-{
-    std::vector<std::string> recipeIds;
-    for (const std::string& recipeId : hypothetical.recipeIds)
-    {
-        if (m_unlockedRecipeIds.count(recipeId) > 0) { continue; }
-        recipeIds.push_back(recipeId);
-    }
-    std::sort(recipeIds.begin(), recipeIds.end(),
-              [](const std::string& lhs, const std::string& rhs)
-              {
-                  return toDisplayName(lhs) < toDisplayName(rhs);
-              });
-    return recipeIds;
-}
-
 bool Simulation::isRecipeUnlocked(const std::string& recipeId) const
 {
-    return m_unlockedRecipeIds.count(recipeId) > 0;
+    return m_unlockState.isRecipeUnlocked(recipeId);
 }
 
 bool Simulation::isItemUnlocked(const std::string& itemId) const
 {
-    return m_unlockedItemIds.count(itemId) > 0;
+    return m_unlockState.isItemUnlocked(itemId);
 }
 
 // ---------------------------------------------------------------------------
 // Determinism (see docs/replay_design.md)
 // ---------------------------------------------------------------------------
 
-void Simulation::appendSchematicMap(Hasher& hasher,
-                                    const std::map<std::string, SchematicState>& levels)
-{
-    hasher.append(levels.size());
-    for (const std::pair<const std::string, SchematicState>& entry : levels)
-    {
-        hasher.append(entry.first);
-        hasher.append(entry.second.unlocked);
-    }
-}
-
-void Simulation::appendStringSet(Hasher& hasher, const std::set<std::string>& ids)
-{
-    hasher.append(ids.size());
-    for (const std::string& id : ids)
-    {
-        hasher.append(id);
-    }
-}
-
 unsigned long long Simulation::getRngFingerprint() const
 {
     return fingerprintRng(m_rng);
@@ -937,13 +664,7 @@ unsigned long long Simulation::computeStateChecksum() const
     hasher.append(getNormalGapRemainingTicks());
 
     // Schematic / unlock state (std::map and std::set iterate in sorted order).
-    appendSchematicMap(hasher, m_schematicLevels);
-    appendSchematicMap(hasher, m_moduleSchematicLevels);
-    appendSchematicMap(hasher, m_buildingLevels);
-    appendStringSet(hasher, m_awardedUnlockGroupIds);
-    appendStringSet(hasher, m_unlockedRecipeSchematicIds);
-    appendStringSet(hasher, m_unlockedRecipeIds);
-    appendStringSet(hasher, m_unlockedItemIds);
+    m_unlockState.appendChecksum(hasher);
 
     // Subsystems contribute their own state.
     m_buildingSystem->appendChecksum(hasher);
@@ -1114,37 +835,17 @@ Tick Simulation::getNormalGapRemainingTicks() const
 
 bool Simulation::isSchematicUnlocked(const std::string& shipId) const
 {
-    const std::map<std::string, SchematicState>::const_iterator it =
-        m_schematicLevels.find(shipId);
-    if (it == m_schematicLevels.end())
-    {
-        return false;
-    }
-    return it->second.unlocked;
+    return m_unlockState.isSchematicUnlocked(shipId);
 }
 
 bool Simulation::isModuleSchematicUnlocked(const std::string& moduleId) const
 {
-    const std::map<std::string, SchematicState>::const_iterator it =
-        m_moduleSchematicLevels.find(moduleId);
-    if (it == m_moduleSchematicLevels.end())
-    {
-        return false;
-    }
-    return it->second.unlocked;
+    return m_unlockState.isModuleSchematicUnlocked(moduleId);
 }
 
 bool Simulation::isBuildingUnlocked(BuildingType type) const
 {
-    const BuildingDef* def = m_config.buildings.findBuildingDef(type);
-    if (def == nullptr)
-    {
-        // Types without a config entry (e.g. HQ, defence stations) are unrestricted.
-        return true;
-    }
-    const std::map<std::string, SchematicState>::const_iterator it =
-        m_buildingLevels.find(def->id);
-    return it == m_buildingLevels.end() ? true : it->second.unlocked;
+    return m_unlockState.isBuildingUnlocked(type);
 }
 
 std::optional<BuildingId> Simulation::tryPlaceBuilding(BuildingType type, QPoint anchor, Rotation rotation)

src/lib/sim/Simulation.h

@@ -1,10 +1,8 @@
 #pragma once
 
-#include <map>
 #include <memory>
 #include <optional>
 #include <random>
-#include <set>
 #include <string>
 #include <vector>
 
@@ -22,6 +20,7 @@
 #include "Rotation.h"
 #include "Tick.h"
 #include "TracePrintRequestedEvent.h"
+#include "UnlockState.h"
 
 class AiSystem;
 class BuildingSystem;
@@ -203,69 +202,11 @@ private:
     entt::entity m_playerStation2Entity;
     entt::entity m_currentEnemyStationEntities[2];
 
-    // Schematic unlock state (REQ-DEF-SCHEMATIC-DROP).
-    struct SchematicState
-    {
-        bool unlocked;
-    };
-    std::map<std::string, SchematicState> m_schematicLevels;
-    std::map<std::string, SchematicState> m_moduleSchematicLevels;
-    std::map<std::string, SchematicState> m_buildingLevels;
-
-    // Unlock groups awarded so far (REQ-LOCK-EXPLICIT). Group ids.
-    std::set<std::string> m_awardedUnlockGroupIds;
-
-    // Ids granted by some unlock group, per kind — cached from config at init.
-    // An item starts locked iff it appears in the corresponding set.
-    std::set<std::string> m_grantedShipIds;
-    std::set<std::string> m_grantedModuleIds;
-    std::set<std::string> m_grantedBuildingIds;
-    std::set<std::string> m_grantedRecipeIds;
-
-    // Builds the granted-id sets and initializes all per-item unlock maps from
-    // them (shared by the constructor and reset). Ends with recomputeUnlocked().
-    void initializeUnlockState();
-
-    // Builds a schematic choice option for one unlock group (REQ-DEF-SCHEMATIC-DROP).
-    SchematicChoiceOption makeUnlockOption(const UnlockGroupDef& group) const;
-
-    // Determinism helpers — fold sub-state into the hasher in deterministic order.
-    static void appendSchematicMap(Hasher& hasher,
-                                   const std::map<std::string, SchematicState>& levels);
-    static void appendStringSet(Hasher& hasher, const std::set<std::string>& ids);
-
-    // Explicitly unlocked assembler recipe schematics (REQ-LOCK-EXPLICIT).
-    std::set<std::string> m_unlockedRecipeSchematicIds;
-
-    // Implicit unlock sets derived from schematic state (REQ-LOCK-IMPLICIT).
-    std::set<std::string> m_unlockedRecipeIds;
-    std::set<std::string> m_unlockedItemIds;
-
-    // Recomputes m_unlockedRecipeIds and m_unlockedItemIds from current schematic state.
-    void recomputeUnlocked();
-
-    // Result of the REQ-LOCK-IMPLICIT traversal.
-    struct UnlockedSets
-    {
-        std::set<std::string> itemIds;
-        std::set<std::string> recipeIds;
-    };
-
-    // Pure REQ-LOCK-IMPLICIT traversal given hypothetical explicit-unlock sets.
-    UnlockedSets computeUnlockedSets(const std::set<std::string>& unlockedShipSchematicIds,
-                                      const std::set<std::string>& unlockedModuleSchematicIds,
-                                      const std::set<std::string>& unlockedRecipeSchematicIds) const;
-
-    // Current explicit-unlock id sets, derived from m_schematicLevels / m_moduleSchematicLevels.
-    std::set<std::string> getUnlockedShipSchematicIds() const;
-    std::set<std::string> getUnlockedModuleSchematicIds() const;
-
-    // True if every prerequisite unlock group has been awarded (REQ-LOCK-PREREQ).
-    bool prerequisitesSatisfied(const std::vector<std::string>& requiredGroupIds) const;
-
-    // Ids (sorted alphabetically by display name) of the recipes in
-    // hypothetical.recipeIds that are not yet in m_unlockedRecipeIds.
-    std::vector<std::string> computeNewlyUnlockedRecipeIds(const UnlockedSets& hypothetical) const;
+    // Schematic/unlock bookkeeping (REQ-DEF-SCHEMATIC-DROP, REQ-LOCK-EXPLICIT,
+    // REQ-LOCK-IMPLICIT, REQ-LOCK-BUILDING, REQ-LOCK-PREREQ). Constructed before
+    // initializeSubsystems() runs since BuildingSystem's spawn-gating lambda
+    // calls into it (see initializeSubsystems()).
+    UnlockState m_unlockState;
 
     EntityAdmin                       m_admin;
     BeltSystem                        m_beltSystem;

src/lib/sim/UnlockState.cpp

@@ -0,0 +1,352 @@
+#include "UnlockState.h"
+
+#include <algorithm>
+
+#include "DisplayName.h"
+#include "StateChecksum.h"
+
+UnlockState::UnlockState(const GameConfig& config)
+    : m_config(config)
+{
+}
+
+void UnlockState::initializeUnlockState()
+{
+    // Cache the ids granted by some unlock group (REQ-LOCK-EXPLICIT); an item
+    // starts locked iff it is granted by a group.
+    m_grantedShipIds.clear();
+    m_grantedModuleIds.clear();
+    m_grantedBuildingIds.clear();
+    m_grantedRecipeIds.clear();
+    for (const UnlockGroupDef& group : m_config.unlocks.groups)
+    {
+        m_grantedShipIds.insert(group.ships.begin(), group.ships.end());
+        m_grantedModuleIds.insert(group.modules.begin(), group.modules.end());
+        m_grantedBuildingIds.insert(group.buildings.begin(), group.buildings.end());
+        m_grantedRecipeIds.insert(group.recipes.begin(), group.recipes.end());
+    }
+
+    m_awardedUnlockGroupIds.clear();
+
+    m_schematicLevels.clear();
+    for (const ShipDef& def : m_config.ships.ships)
+    {
+        SchematicState state;
+        state.unlocked = (m_grantedShipIds.count(def.id) == 0);
+        m_schematicLevels[def.id] = state;
+    }
+
+    m_moduleSchematicLevels.clear();
+    for (const ModuleDef& def : m_config.modules.modules)
+    {
+        SchematicState state;
+        state.unlocked = (m_grantedModuleIds.count(def.id) == 0);
+        m_moduleSchematicLevels[def.id] = state;
+    }
+
+    m_buildingLevels.clear();
+    for (const BuildingDef& def : m_config.buildings.buildings)
+    {
+        SchematicState state;
+        state.unlocked = (m_grantedBuildingIds.count(def.id) == 0);
+        m_buildingLevels[def.id] = state;
+    }
+
+    // Gated assembler recipes start locked; unlocked_at_start recipes are handled
+    // in the REQ-LOCK-IMPLICIT traversal, not tracked here.
+    m_unlockedRecipeSchematicIds.clear();
+
+    recomputeUnlocked();
+}
+
+bool UnlockState::isSchematicUnlocked(const std::string& shipId) const
+{
+    const std::map<std::string, SchematicState>::const_iterator it =
+        m_schematicLevels.find(shipId);
+    if (it == m_schematicLevels.end())
+    {
+        return false;
+    }
+    return it->second.unlocked;
+}
+
+bool UnlockState::isModuleSchematicUnlocked(const std::string& moduleId) const
+{
+    const std::map<std::string, SchematicState>::const_iterator it =
+        m_moduleSchematicLevels.find(moduleId);
+    if (it == m_moduleSchematicLevels.end())
+    {
+        return false;
+    }
+    return it->second.unlocked;
+}
+
+bool UnlockState::isRecipeUnlocked(const std::string& recipeId) const
+{
+    return m_unlockedRecipeIds.count(recipeId) > 0;
+}
+
+bool UnlockState::isItemUnlocked(const std::string& itemId) const
+{
+    return m_unlockedItemIds.count(itemId) > 0;
+}
+
+bool UnlockState::isBuildingUnlocked(BuildingType type) const
+{
+    const BuildingDef* def = m_config.buildings.findBuildingDef(type);
+    if (def == nullptr)
+    {
+        // Types without a config entry (e.g. HQ, defence stations) are unrestricted.
+        return true;
+    }
+    const std::map<std::string, SchematicState>::const_iterator it =
+        m_buildingLevels.find(def->id);
+    return it == m_buildingLevels.end() ? true : it->second.unlocked;
+}
+
+bool UnlockState::isUnlockGroupAwarded(const std::string& groupId) const
+{
+    return m_awardedUnlockGroupIds.count(groupId) > 0;
+}
+
+bool UnlockState::prerequisitesSatisfied(const std::vector<std::string>& requiredGroupIds) const
+{
+    // A prerequisite is satisfied only once the named unlock group has been
+    // awarded (REQ-LOCK-PREREQ).
+    for (const std::string& groupId : requiredGroupIds)
+    {
+        if (m_awardedUnlockGroupIds.count(groupId) == 0) { return false; }
+    }
+    return true;
+}
+
+SchematicChoiceOption UnlockState::makeUnlockOption(const UnlockGroupDef& group) const
+{
+    SchematicChoiceOption option;
+    option.isArtifact    = false;
+    option.unlockGroupId = group.id;
+    option.displayName   = toDisplayName(group.id);
+
+    for (const std::string& id : group.ships)
+    {
+        option.grantedItems.push_back({SchematicType::Ship, id, toDisplayName(id)});
+    }
+    for (const std::string& id : group.modules)
+    {
+        option.grantedItems.push_back({SchematicType::Module, id, toDisplayName(id)});
+    }
+    for (const std::string& id : group.buildings)
+    {
+        option.grantedItems.push_back({SchematicType::Building, id, toDisplayName(id)});
+    }
+    for (const std::string& id : group.recipes)
+    {
+        option.grantedItems.push_back({SchematicType::Recipe, id, toDisplayName(id)});
+    }
+
+    // REQ-DEF-SCHEMATIC-DROP: preview recipes newly implicitly unlocked by
+    // awarding this whole group. Seed the hypothetical explicit-unlock sets with
+    // every grant (ship + module materials via step 1a, recipe outputs via step
+    // 1b), then diff against the current implicit set.
+    std::set<std::string> hypotheticalShipIds            = getUnlockedShipSchematicIds();
+    std::set<std::string> hypotheticalModuleIds          = getUnlockedModuleSchematicIds();
+    std::set<std::string> hypotheticalRecipeSchematicIds = m_unlockedRecipeSchematicIds;
+    for (const std::string& id : group.ships)   { hypotheticalShipIds.insert(id); }
+    for (const std::string& id : group.modules) { hypotheticalModuleIds.insert(id); }
+    for (const std::string& id : group.recipes) { hypotheticalRecipeSchematicIds.insert(id); }
+
+    const UnlockedSets hypothetical = computeUnlockedSets(
+        hypotheticalShipIds, hypotheticalModuleIds, hypotheticalRecipeSchematicIds);
+    option.newlyUnlockedRecipeIds = computeNewlyUnlockedRecipeIds(hypothetical);
+
+    return option;
+}
+
+void UnlockState::awardUnlockGroup(const SchematicChoiceOption& chosen)
+{
+    // Award the whole unlock group (REQ-DEF-SCHEMATIC-DROP): unlock every granted
+    // ship, module, building, and assembler recipe at once.
+    m_awardedUnlockGroupIds.insert(chosen.unlockGroupId);
+    for (const GrantedSchematic& grant : chosen.grantedItems)
+    {
+        switch (grant.type)
+        {
+        case SchematicType::Ship:     m_schematicLevels.at(grant.id).unlocked = true;       break;
+        case SchematicType::Module:   m_moduleSchematicLevels.at(grant.id).unlocked = true; break;
+        case SchematicType::Building: m_buildingLevels.at(grant.id).unlocked = true;        break;
+        case SchematicType::Recipe:   m_unlockedRecipeSchematicIds.insert(grant.id);        break;
+        }
+    }
+
+    recomputeUnlocked();
+}
+
+// ---------------------------------------------------------------------------
+// Implicit unlock computation (REQ-LOCK-IMPLICIT)
+// ---------------------------------------------------------------------------
+
+void UnlockState::recomputeUnlocked()
+{
+    const UnlockedSets result = computeUnlockedSets(
+        getUnlockedShipSchematicIds(), getUnlockedModuleSchematicIds(), m_unlockedRecipeSchematicIds);
+    m_unlockedItemIds   = result.itemIds;
+    m_unlockedRecipeIds = result.recipeIds;
+}
+
+std::set<std::string> UnlockState::getUnlockedShipSchematicIds() const
+{
+    std::set<std::string> ids;
+    for (const auto& [id, state] : m_schematicLevels)
+    {
+        if (state.unlocked) { ids.insert(id); }
+    }
+    return ids;
+}
+
+std::set<std::string> UnlockState::getUnlockedModuleSchematicIds() const
+{
+    std::set<std::string> ids;
+    for (const auto& [id, state] : m_moduleSchematicLevels)
+    {
+        if (state.unlocked) { ids.insert(id); }
+    }
+    return ids;
+}
+
+UnlockState::UnlockedSets UnlockState::computeUnlockedSets(
+    const std::set<std::string>& unlockedShipSchematicIds,
+    const std::set<std::string>& unlockedModuleSchematicIds,
+    const std::set<std::string>& unlockedRecipeSchematicIds) const
+{
+    UnlockedSets result;
+
+    for (const ShipDef& def : m_config.ships.ships)
+    {
+        if (unlockedShipSchematicIds.count(def.id) == 0) { continue; }
+        for (const RecipeIngredient& mat : def.schematic.materials)
+        {
+            result.itemIds.insert(mat.item);
+        }
+    }
+    for (const ModuleDef& def : m_config.modules.modules)
+    {
+        if (unlockedModuleSchematicIds.count(def.id) == 0) { continue; }
+        for (const RecipeIngredient& mat : def.materials)
+        {
+            result.itemIds.insert(mat.item);
+        }
+    }
+    for (const RecipeDef& def : m_config.recipes.recipes)
+    {
+        // An assembler recipe seeds the base set when it is explicitly available:
+        // flagged unlocked_at_start (base recipes the graph can't reach), or a
+        // gated recipe whose unlock group has been awarded (REQ-LOCK-EXPLICIT).
+        if (def.building == BuildingType::Assembler
+            && (def.unlockedAtStart || unlockedRecipeSchematicIds.count(def.id) > 0))
+        {
+            for (const RecipeOutput& out : def.outputs)
+            {
+                result.itemIds.insert(out.item);
+            }
+        }
+    }
+
+    bool changed = true;
+    while (changed)
+    {
+        changed = false;
+        for (const RecipeDef& recipe : m_config.recipes.recipes)
+        {
+            if (recipe.building != BuildingType::Miner
+                && recipe.building != BuildingType::Smelter
+                && recipe.building != BuildingType::Assembler)
+            {
+                continue;
+            }
+            // Skip a gated assembler recipe (granted by an unlock group) whose
+            // group has not yet been awarded (REQ-LOCK-IMPLICIT step 2).
+            if (recipe.building == BuildingType::Assembler
+                && m_grantedRecipeIds.count(recipe.id) > 0
+                && unlockedRecipeSchematicIds.count(recipe.id) == 0)
+            {
+                continue;
+            }
+            bool producesUnlocked = false;
+            for (const RecipeOutput& out : recipe.outputs)
+            {
+                if (result.itemIds.count(out.item) > 0)
+                {
+                    producesUnlocked = true;
+                    break;
+                }
+            }
+            if (!producesUnlocked) { continue; }
+
+            if (recipe.building == BuildingType::Miner
+                || recipe.building == BuildingType::Assembler)
+            {
+                result.recipeIds.insert(recipe.id);
+            }
+            for (const RecipeIngredient& ing : recipe.inputs)
+            {
+                if (result.itemIds.insert(ing.item).second)
+                {
+                    changed = true;
+                }
+            }
+        }
+    }
+
+    return result;
+}
+
+std::vector<std::string> UnlockState::computeNewlyUnlockedRecipeIds(const UnlockedSets& hypothetical) const
+{
+    std::vector<std::string> recipeIds;
+    for (const std::string& recipeId : hypothetical.recipeIds)
+    {
+        if (m_unlockedRecipeIds.count(recipeId) > 0) { continue; }
+        recipeIds.push_back(recipeId);
+    }
+    std::sort(recipeIds.begin(), recipeIds.end(),
+              [](const std::string& lhs, const std::string& rhs)
+              {
+                  return toDisplayName(lhs) < toDisplayName(rhs);
+              });
+    return recipeIds;
+}
+
+// ---------------------------------------------------------------------------
+// Determinism (see docs/replay_design.md)
+// ---------------------------------------------------------------------------
+
+void UnlockState::appendSchematicMap(Hasher& hasher,
+                                     const std::map<std::string, SchematicState>& levels)
+{
+    hasher.append(levels.size());
+    for (const std::pair<const std::string, SchematicState>& entry : levels)
+    {
+        hasher.append(entry.first);
+        hasher.append(entry.second.unlocked);
+    }
+}
+
+void UnlockState::appendStringSet(Hasher& hasher, const std::set<std::string>& ids)
+{
+    hasher.append(ids.size());
+    for (const std::string& id : ids)
+    {
+        hasher.append(id);
+    }
+}
+
+void UnlockState::appendChecksum(Hasher& hasher) const
+{
+    appendSchematicMap(hasher, m_schematicLevels);
+    appendSchematicMap(hasher, m_moduleSchematicLevels);
+    appendSchematicMap(hasher, m_buildingLevels);
+    appendStringSet(hasher, m_awardedUnlockGroupIds);
+    appendStringSet(hasher, m_unlockedRecipeSchematicIds);
+    appendStringSet(hasher, m_unlockedRecipeIds);
+    appendStringSet(hasher, m_unlockedItemIds);
+}

src/lib/sim/UnlockState.h

@@ -0,0 +1,129 @@
+#pragma once
+
+#include <map>
+#include <set>
+#include <string>
+#include <vector>
+
+#include "BuildingType.h"
+#include "GameConfig.h"
+#include "SchematicChoiceOption.h"
+
+class Hasher;
+
+// Owns schematic/unlock bookkeeping for one run: which ship, module, and
+// building schematics are unlocked (REQ-LOCK-EXPLICIT), which assembler recipe
+// schematics have been explicitly granted, and the implicit recipe/item unlock
+// sets derived from that state (REQ-LOCK-IMPLICIT). Reads config the same way
+// BuildingSystem does (a bound const reference to Simulation::m_config, which is
+// safe across restart because that member's storage address never changes —
+// reset() move-assigns into it rather than replacing it).
+//
+// Simulation forwards its isXUnlocked-style public queries here and drives
+// state changes (awarding an unlock group) here; the RNG-touching schematic
+// choice generation itself stays in Simulation (call ordering of m_rng is the
+// determinism backbone and must not move).
+class UnlockState
+{
+public:
+    explicit UnlockState(const GameConfig& config);
+
+    // Builds the granted-id sets and initializes all per-item unlock maps from
+    // them (shared by the constructor and Simulation::reset). Ends with
+    // recomputeUnlocked().
+    void initializeUnlockState();
+
+    // Ship schematic state query.
+    bool isSchematicUnlocked(const std::string& shipId) const;
+
+    // Module schematic state query.
+    bool isModuleSchematicUnlocked(const std::string& moduleId) const;
+
+    // Implicit recipe/item unlock queries (REQ-LOCK-IMPLICIT).
+    bool isRecipeUnlocked(const std::string& recipeId) const;
+    bool isItemUnlocked(const std::string& itemId) const;
+
+    // Building unlock query (REQ-LOCK-BUILDING). True if the building type is not
+    // gated by any unlock group, or its granting group has been awarded.
+    bool isBuildingUnlocked(BuildingType type) const;
+
+    // True if the unlock group has already been awarded to the player.
+    bool isUnlockGroupAwarded(const std::string& groupId) const;
+
+    // True if every prerequisite unlock group has been awarded (REQ-LOCK-PREREQ).
+    bool prerequisitesSatisfied(const std::vector<std::string>& requiredGroupIds) const;
+
+    // Builds a schematic choice option for one unlock group (REQ-DEF-SCHEMATIC-DROP).
+    SchematicChoiceOption makeUnlockOption(const UnlockGroupDef& group) const;
+
+    // Awards the unlock group backing `chosen` (REQ-DEF-SCHEMATIC-DROP): marks
+    // every granted ship/module/building schematic unlocked, records granted
+    // recipe schematics, marks the group as awarded, and recomputes the implicit
+    // unlock sets. Mirrors the non-artifact branch of the original
+    // Simulation::applySchematicChoice exactly; callers still special-case
+    // chosen.isArtifact themselves before calling this.
+    void awardUnlockGroup(const SchematicChoiceOption& chosen);
+
+    // Determinism helper (see Simulation::computeStateChecksum): folds unlock
+    // state into the hasher via the same seven calls, in the same order, that
+    // used to live at the Simulation::computeStateChecksum call site.
+    void appendChecksum(Hasher& hasher) const;
+
+private:
+    // Schematic unlock state (REQ-DEF-SCHEMATIC-DROP).
+    struct SchematicState
+    {
+        bool unlocked;
+    };
+
+    // Recomputes m_unlockedRecipeIds and m_unlockedItemIds from current schematic state.
+    void recomputeUnlocked();
+
+    // Result of the REQ-LOCK-IMPLICIT traversal.
+    struct UnlockedSets
+    {
+        std::set<std::string> itemIds;
+        std::set<std::string> recipeIds;
+    };
+
+    // Pure REQ-LOCK-IMPLICIT traversal given hypothetical explicit-unlock sets.
+    UnlockedSets computeUnlockedSets(const std::set<std::string>& unlockedShipSchematicIds,
+                                      const std::set<std::string>& unlockedModuleSchematicIds,
+                                      const std::set<std::string>& unlockedRecipeSchematicIds) const;
+
+    // Current explicit-unlock id sets, derived from m_schematicLevels / m_moduleSchematicLevels.
+    std::set<std::string> getUnlockedShipSchematicIds() const;
+    std::set<std::string> getUnlockedModuleSchematicIds() const;
+
+    // Ids (sorted alphabetically by display name) of the recipes in
+    // hypothetical.recipeIds that are not yet in m_unlockedRecipeIds.
+    std::vector<std::string> computeNewlyUnlockedRecipeIds(const UnlockedSets& hypothetical) const;
+
+    // Determinism helpers — fold sub-state into the hasher in deterministic order.
+    static void appendSchematicMap(Hasher& hasher,
+                                   const std::map<std::string, SchematicState>& levels);
+    static void appendStringSet(Hasher& hasher, const std::set<std::string>& ids);
+
+    const GameConfig& m_config;
+
+    std::map<std::string, SchematicState> m_schematicLevels;
+    std::map<std::string, SchematicState> m_moduleSchematicLevels;
+    std::map<std::string, SchematicState> m_buildingLevels;
+
+    // Unlock groups awarded so far (REQ-LOCK-EXPLICIT). Group ids.
+    std::set<std::string> m_awardedUnlockGroupIds;
+
+    // Ids granted by some unlock group, per kind — cached from config at init.
+    // An item starts locked iff it appears in the corresponding set.
+    std::set<std::string> m_grantedShipIds;
+    std::set<std::string> m_grantedModuleIds;
+    std::set<std::string> m_grantedBuildingIds;
+    std::set<std::string> m_grantedRecipeIds;
+
+    // Explicitly unlocked assembler recipe schematics (REQ-LOCK-EXPLICIT).
+    std::set<std::string> m_unlockedRecipeSchematicIds;
+
+    // Implicit unlock sets derived from schematic state (REQ-LOCK-IMPLICIT).
+    std::set<std::string> m_unlockedRecipeIds;
+    std::set<std::string> m_unlockedItemIds;
+};

src/test/DeterminismTest.cpp

@@ -5,11 +5,15 @@
 #include <vector>
 
 #include "ConfigLoader.h"
+#include "FactionComponent.h"
 #include "GameConfig.h"
+#include "HealthComponent.h"
 #include "Rotation.h"
+#include "SchematicChoiceOption.h"
 #include "Simulation.h"
 #include "SimulationTestAccess.h"
 #include "StateChecksum.h"
+#include "StationBodyComponent.h"
 #include "Tick.h"
 #include "TestConfig.h"
 
@@ -17,9 +21,33 @@ namespace
 {
 constexpr int kScriptTicks = 2000;
 
+// Ticks at which the scripted session destroys the enemy stations, and the ticks
+// on which the resulting schematic choice is taken. A station dying triggers the
+// choice generation (REQ-DEF-SCHEMATIC-DROP), which lands during that same tick,
+// so the choice is applied on the tick after.
+constexpr int kFirstStationKillTick  = 800;
+constexpr int kFirstChoiceTick       = kFirstStationKillTick + 1;
+constexpr int kSecondStationKillTick = 1400;
+constexpr int kSecondChoiceTick      = kSecondStationKillTick + 1;
+
+// Zeroes the HP of every enemy station, so the next tick processes their death.
+void killEnemyStations(Simulation& sim)
+{
+    sim.getAdmin().forEach<StationBodyComponent, FactionComponent, HealthComponent>(
+        [](entt::entity, StationBodyComponent&, FactionComponent& faction,
+           HealthComponent& health)
+        {
+            if (faction.isEnemy) { health.hp = 0.0f; }
+        });
+}
+
 // Runs a fixed scripted session and returns the full-state checksum after every
 // tick. The script places a small factory, deconstructs part of it mid-run, and
 // otherwise lets waves/combat run so the RNG stream and ECS state are exercised.
+// It also destroys the enemy stations twice and takes the offered schematic
+// choice, so that unlock state (awarded groups, per-schematic levels, and the
+// implicit recipe/item sets derived from them) is exercised as well and reaches
+// the checksum via UnlockState::appendChecksum.
 std::vector<std::uint64_t> runScriptedSession(unsigned int seed)
 {
     Simulation sim(loadTestConfig(), seed);
@@ -40,6 +68,26 @@ std::vector<std::uint64_t> runScriptedSession(unsigned int seed)
             SimulationTestAccess::place(sim, BuildingType::Smelter, QPoint(-3, 3), Rotation::East);
         }
 
+        if (t == kFirstStationKillTick || t == kSecondStationKillTick)
+        {
+            killEnemyStations(sim);
+        }
+
+        if (t == kFirstChoiceTick)
+        {
+            // Guarded rather than assumed: if the test config ever stops offering
+            // a group here, this script would silently stop covering unlock state.
+            REQUIRE(sim.hasSchematicChoicesPending());
+            SimulationTestAccess::applySchematicChoice(sim, 0);
+        }
+
+        // The second award is opportunistic — whether a group is still eligible
+        // depends on what the first one granted and on the prerequisite gating.
+        if (t == kSecondChoiceTick && sim.hasSchematicChoicesPending())
+        {
+            SimulationTestAccess::applySchematicChoice(sim, 0);
+        }
+
         sim.tick();
         checksums.push_back(sim.computeStateChecksum());
     }
@@ -152,3 +200,44 @@ TEST_CASE("Simulation: different seeds diverge in state checksum", "[determinism
     // the RNG-driven divergence; a constant checksum would be a broken hash).
     REQUIRE(a != b);
 }
+
+// ---------------------------------------------------------------------------
+// Unlock state coverage
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Simulation: unlock state contributes to the state checksum",
+          "[determinism][unlock]")
+{
+    // Two sessions with identical history up to the schematic choice; only one
+    // takes the choice. This pins down that awarding an unlock group actually
+    // reaches the checksum, which the scripted-session tests above rely on but
+    // cannot show on their own: they would still pass if UnlockState were left
+    // out of the fold entirely.
+    Simulation taken(loadTestConfig(), 12345u);
+    Simulation skipped(loadTestConfig(), 12345u);
+
+    for (int t = 0; t < kFirstStationKillTick; ++t)
+    {
+        taken.tick();
+        skipped.tick();
+    }
+    killEnemyStations(taken);
+    killEnemyStations(skipped);
+    taken.tick();
+    skipped.tick();
+
+    // In lockstep before the choice, so the divergence below has one cause.
+    REQUIRE(taken.computeStateChecksum() == skipped.computeStateChecksum());
+
+    REQUIRE(taken.hasSchematicChoicesPending());
+
+    // An artifact choice bumps m_artifactCount, which is folded separately; the
+    // divergence would then not be attributable to unlock state.
+    REQUIRE_FALSE(taken.getPendingSchematicChoices()[0].isArtifact);
+
+    SimulationTestAccess::applySchematicChoice(taken, 0);
+
+    // The pending-choice list is not itself folded into the checksum, so the
+    // only state that changed is the unlock bookkeeping.
+    REQUIRE(taken.computeStateChecksum() != skipped.computeStateChecksum());
+}