feat: add seed signatures for entities and components

- Store per-component random seed in entity entries, accessible
  via entity.seed(key) for replay and debugging
- Store entity-level seed derived from the generation engine,
  accessible via entity.seed() to reproduce all component seeds
- Seed hierarchy: generation seed → entity seed → per-component seeds
- Each component now gets its own seeded random engine instead of
  sharing one for the whole entity
- Add Seed Signatures section to README with usage examples and
  seed hierarchy diagram
- Add 9 new tests covering entity/component seed retrieval,
  determinism, replay, and error handling (52 total, 100% coverage)

Author: dasmig

README.md

@@ -30,6 +30,8 @@ The library currently supports the following:
 
 - **Reproducible Randomness**. Seed the generator for deterministic output. Supports per-call seeds and generator-level seeding for reproducible sequences.
 
+- **Seed Signatures**. Every generated entity and component stores the random seed used to produce it, enabling replay and debugging.
+
 - **Fluent Registration**. Chain `add()` and `remove()` calls to configure the generator.
 
 - **Composable**. Components can internally use [name-generator](https://github.com/dasmig/name-generator) and [nickname-generator](https://github.com/dasmig/nickname-generator) or any other logic.
@@ -232,4 +234,39 @@ class position : public dasmig::component
         return L"(" + std::to_wstring(pos.x) + L", " + std::to_wstring(pos.y) + L")";
     }
 };
+```
+
+### Seed Signatures
+
+Every generated entity and component stores the random seed that produced it. This enables replay, debugging, and logging.
+
+```cpp
+auto entity = eg::instance().generate();
+
+// Retrieve the entity-level seed. This single value can reproduce
+// all component seeds and thus the entire entity.
+std::uint64_t entity_seed = entity.seed();
+
+// Retrieve the seed used for a specific component.
+std::uint64_t age_seed = entity.seed(L"age");
+```
+
+Component seeds can be used to replay individual component generation:
+
+```cpp
+// Replay a component's random values using its captured seed.
+effolkronium::random_local rng;
+rng.seed(static_cast<std::mt19937::result_type>(entity.seed(L"age")));
+int replayed_age = rng.get(18, 65); // Same value as entity.get<int>(L"age")
+```
+
+The seed hierarchy is fully deterministic:
+
+```
+generation seed (per-call or generator-level)
+  └─ entity seed          ← entity.seed()
+       └─ local engine
+            ├─ component A seed   ← entity.seed(L"A")
+            ├─ component B seed   ← entity.seed(L"B")
+            └─ ...
 ```

dasmig/entitygen.hpp

@@ -135,6 +135,27 @@ class entity
         });
     }
 
+    // Retrieve the random seed used to generate a specific component.
+    // This seed can be used to reproduce the component's random values.
+    [[nodiscard]] std::uint64_t seed(const std::wstring& component_key) const
+    {
+        auto it = std::ranges::find(_entries, component_key, &entry::key);
+
+        if (it == _entries.end())
+        {
+            throw std::out_of_range("component not found");
+        }
+
+        return it->seed;
+    }
+
+    // Retrieve the random seed used to generate this entity. This seed
+    // can reproduce all component seeds and thus the entire entity.
+    [[nodiscard]] std::uint64_t seed() const
+    {
+        return _seed;
+    }
+
     // Get all component keys present in this entity, in generation order.
     [[nodiscard]] std::vector<std::wstring> keys() const
     {
@@ -167,6 +188,7 @@ class entity
         std::wstring key;
         std::any value;
         std::wstring display;
+        std::uint64_t seed;
     };
 
     // Private constructor, this is mostly a helper class to the entity
@@ -189,6 +211,9 @@ class entity
     // Component entries in generation order.
     std::vector<entry> _entries;
 
+    // Seed used to generate this entity.
+    std::uint64_t _seed{0};
+
     // Allows entity generator to construct entities.
     friend class eg;
 };
@@ -351,17 +376,26 @@ class eg
     {
         entity generated_entity;
         generation_context ctx;
-        ctx._random.seed(engine());
+
+        // Derive an entity-level seed and use it to create a local engine
+        // for per-component seed derivation.
+        auto entity_seed = static_cast<std::uint64_t>(engine());
+        generated_entity._seed = entity_seed;
+        std::mt19937 local_engine{static_cast<std::mt19937::result_type>(entity_seed)};
 
         for (const auto& [key, comp] : components)
         {
+            auto component_seed = static_cast<std::uint64_t>(local_engine());
+            ctx._random.seed(static_cast<std::mt19937::result_type>(component_seed));
+
             auto value = comp->generate(ctx);
             auto display = comp->to_string(value);
 
             ctx._values[key] = value;
             generated_entity._entries.push_back(
                 {.key = key, .value = std::move(value),
-                 .display = std::move(display)});
+                 .display = std::move(display),
+                 .seed = component_seed});
         }
 
         return generated_entity;

tests/tests.cpp

@@ -913,3 +913,140 @@ TEST_CASE("seeded generation reproduces dependent computed values", "[context][s
 
     REQUIRE(e1.get<int>(L"scaled") == e2.get<int>(L"scaled"));
 }
+
+// ---------------------------------------------------------------------------
+// Component seed signature
+// ---------------------------------------------------------------------------
+
+TEST_CASE("entity::seed returns the seed used for a component", "[seed][signature]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"rand", 1, 10000));
+
+    auto e = gen.generate(42);
+    // Should not throw — seed exists for every generated component.
+    REQUIRE_NOTHROW(e.seed(L"rand"));
+}
+
+TEST_CASE("same generation seed produces same component seeds", "[seed][signature]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"a", 1, 10000))
+       .add(std::make_unique<random_int_component>(L"b", 1, 10000));
+
+    auto e1 = gen.generate(42);
+    auto e2 = gen.generate(42);
+
+    REQUIRE(e1.seed(L"a") == e2.seed(L"a"));
+    REQUIRE(e1.seed(L"b") == e2.seed(L"b"));
+}
+
+TEST_CASE("different components get different seeds", "[seed][signature]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"a", 1, 10000))
+       .add(std::make_unique<random_int_component>(L"b", 1, 10000));
+
+    auto e = gen.generate(42);
+
+    // Each component should be seeded independently.
+    REQUIRE(e.seed(L"a") != e.seed(L"b"));
+}
+
+TEST_CASE("component seed reproduces the same value when used directly", "[seed][signature]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"rand", 1, 10000));
+
+    auto e = gen.generate(42);
+    auto captured_seed = e.seed(L"rand");
+    int original_value = e.get<int>(L"rand");
+
+    // Manually seed a random engine with the captured seed and generate.
+    effolkronium::random_local rng;
+    rng.seed(static_cast<std::mt19937::result_type>(captured_seed));
+    int replayed_value = rng.get(1, 10000);
+
+    REQUIRE(original_value == replayed_value);
+}
+
+TEST_CASE("entity::seed throws on missing key", "[seed][signature]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<string_component>(L"a", L"hi"));
+    auto e = gen.generate();
+
+    REQUIRE_THROWS_AS(e.seed(L"missing"), std::out_of_range);
+}
+
+// ---------------------------------------------------------------------------
+// Entity-level seed
+// ---------------------------------------------------------------------------
+
+TEST_CASE("entity::seed() returns the entity-level seed", "[seed][entity]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"rand", 1, 10000));
+
+    auto e = gen.generate(42);
+    // Should not throw — every entity has a seed.
+    REQUIRE_NOTHROW(e.seed());
+    REQUIRE(e.seed() != 0);
+}
+
+TEST_CASE("same generation seed produces same entity seed", "[seed][entity]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"rand", 1, 10000));
+
+    auto e1 = gen.generate(42);
+    auto e2 = gen.generate(42);
+
+    REQUIRE(e1.seed() == e2.seed());
+}
+
+TEST_CASE("different generation seeds produce different entity seeds", "[seed][entity]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"rand", 1, 10000));
+
+    auto e1 = gen.generate(1);
+    auto e2 = gen.generate(2);
+
+    REQUIRE(e1.seed() != e2.seed());
+}
+
+TEST_CASE("entity seed reproduces all component seeds", "[seed][entity]")
+{
+    clear_generator guard;
+    auto& gen = dasmig::eg::instance();
+
+    gen.add(std::make_unique<random_int_component>(L"a", 1, 10000))
+       .add(std::make_unique<random_int_component>(L"b", 1, 10000));
+
+    auto e = gen.generate(42);
+
+    // Derive component seeds from the entity seed the same way generate_impl does.
+    std::mt19937 local_engine{static_cast<std::mt19937::result_type>(e.seed())};
+    auto expected_seed_a = static_cast<std::uint64_t>(local_engine());
+    auto expected_seed_b = static_cast<std::uint64_t>(local_engine());
+
+    REQUIRE(e.seed(L"a") == expected_seed_a);
+    REQUIRE(e.seed(L"b") == expected_seed_b);
+}