entitygen.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: MIT
// Copyright (c) 2020-2026 Diego Dasso Migotto
 
#ifndef DASMIG_ENTITYGEN_HPP
#define DASMIG_ENTITYGEN_HPP
 
#include "core.hpp"
#include <algorithm>
#include <any>
#include <bit>
#include <cmath>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <future>
#include <iterator>
#include <limits>
#include <map>
#include <memory>
#include <optional>
#include <ostream>
#include <ranges>
#include <set>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
/// @file entitygen.hpp
/// @brief Entity generator library — composable, deterministic entity generation for C++23.
/// @author Diego Dasso Migotto (diegomigotto at hotmail dot com)
/// @see See doc/usage.md for the narrative tutorial.
 
DASMIG_CORE_REQUIRE(1, 1);
 
namespace dasmig
{
 
/// @brief A component value as JSON: null, a boolean, an integer, a number,
///        a (UTF-8) string, an array or an object.
///
/// Objects keep their members in the order given. Integers convert
/// implicitly to an integer value, floating-point numbers to a number
/// (non-finite ones are written as null).
/// @see component::to_json()
class json_value
{
  public:
    using array = std::vector<json_value>;                          ///< A JSON array.
    using object = std::vector<std::pair<std::string, json_value>>; ///< A JSON object, members in order.
 
    json_value() = default;                          ///< null.
    json_value(std::nullptr_t) {}                    ///< null. // NOLINT(google-explicit-constructor)
    json_value(std::string s) : _v{std::move(s)} {}  ///< A string (UTF-8). // NOLINT(google-explicit-constructor)
    json_value(const char* s) : _v{std::string{s}} {} ///< A string (UTF-8). // NOLINT(google-explicit-constructor)
    json_value(array a) : _v{std::move(a)} {}        ///< An array. // NOLINT(google-explicit-constructor)
    json_value(object o) : _v{std::move(o)} {}       ///< An object. // NOLINT(google-explicit-constructor)
 
    /// @brief A boolean. Only `bool` itself: a pointer (such as a wide
    ///        literal `L"..."`) would otherwise convert and write `true`.
    template <std::same_as<bool> B>
    json_value(B b) : _v{b} {} // NOLINT(google-explicit-constructor)
 
    /// @brief An integer.
    template <std::integral I>
        requires(!std::same_as<I, bool>)
    json_value(I n) : _v{static_cast<std::int64_t>(n)} {} // NOLINT(google-explicit-constructor)
 
    /// @brief A number; a non-finite one is null.
    template <std::floating_point F>
    json_value(F d) // NOLINT(google-explicit-constructor)
    {
        const auto x = static_cast<double>(d);
        if (std::isfinite(x)) _v = x;
    }
 
    /// @brief The array held, or null when this is not an array.
    [[nodiscard]] const array* get_array() const { return std::get_if<array>(&_v); }
    /// @brief The object held, or null when this is not an object.
    [[nodiscard]] const object* get_object() const { return std::get_if<object>(&_v); }
    /// @brief The object held, or null when this is not an object.
    [[nodiscard]] object* get_object() { return std::get_if<object>(&_v); }
 
    /// @brief Write this value.
    /// @param w Writer positioned where a value is allowed.
    void write(core::json_writer& w) const
    {
        std::visit(
            [&w](const auto& x) {
                using X = std::decay_t<decltype(x)>;
                if constexpr (std::is_same_v<X, array>)
                {
                    w.begin_array();
                    for (const auto& item : x) item.write(w);
                    w.end_array();
                }
                else if constexpr (std::is_same_v<X, object>)
                {
                    w.begin_object();
                    for (const auto& [name, item] : x)
                    {
                        w.key(name);
                        item.write(w);
                    }
                    w.end_object();
                }
                else
                {
                    w.value(x);
                }
            },
            _v);
    }
 
  private:
    std::variant<std::nullptr_t, bool, std::int64_t, double, std::string, array, object> _v;
};
 
/// @brief A per-call input value: a boolean, an integer, a number or a string.
///
/// Scalars only, so the inputs can be part of the replay signature.
/// @see entity_request::inputs, generation_context::input()
using input_value = std::variant<bool, std::int64_t, double, std::string>;
 
/// @brief Per-call inputs by name (ordered, so their hash is reproducible).
using input_map = std::map<std::string, input_value, std::less<>>;
 
// Forward declaration.
class eg;
 
/// @brief Context passed to components during generation.
///
/// Provides access to previously generated component values and a seeded
/// random engine. Created and populated by the entity generator; not
/// user-constructible.
/// @see component::generate()
class generation_context
{
  public:
    /// @brief Check if a component value has already been generated.
    /// @param component_key The component key to look up.
    /// @return `true` if a value for the key exists in the context.
    [[nodiscard]] bool has(const std::wstring& component_key) const
    {
        return find_(component_key) != nullptr;
    }
 
    /// @brief Typed retrieval of an already-generated component value.
    /// @tparam T The expected type of the stored value, or a const reference
    ///         to it (`get<const T&>`) to read it without a copy; the
    ///         reference is valid while the entity is being generated.
    /// @param component_key The component key to retrieve.
    /// @return The value cast to @p T.
    /// @throws std::out_of_range If no value for the key was generated (the
    ///         message names the key); declare the dependency with
    ///         component::depends_on() so a request pulls it in.
    /// @throws std::bad_any_cast If @p T does not match the stored type.
    template <typename T>
    [[nodiscard]] T get(const std::wstring& component_key) const
    {
        const auto* value = find_(component_key);
        if (value == nullptr)
        {
            throw std::out_of_range("component '" + core::to_utf8(component_key) +
                                    "' has not been generated");
        }
        return std::any_cast<T>(*value);
    }
 
    /// @brief Typed retrieval that tolerates a missing value.
    /// @tparam T The expected type of the stored value.
    /// @param component_key The component key to retrieve.
    /// @return The value, or an empty optional if none was generated.
    /// @throws std::bad_any_cast If @p T does not match the stored type.
    template <typename T>
    [[nodiscard]] std::optional<T> try_get(const std::wstring& component_key) const
    {
        const auto* value = find_(component_key);
        if (value == nullptr) return std::nullopt;
        return std::any_cast<T>(*value);
    }
 
    /// @brief Typed retrieval with a fallback.
    /// @tparam T The expected type of the stored value.
    /// @param component_key The component key to retrieve.
    /// @param fallback Returned when no value was generated.
    /// @return The value, or @p fallback.
    /// @throws std::bad_any_cast If @p T does not match the stored type.
    template <typename T>
    [[nodiscard]] T get_or(const std::wstring& component_key, T fallback) const
    {
        const auto* value = find_(component_key);
        return value == nullptr ? std::move(fallback) : std::any_cast<T>(*value);
    }
 
    /// @brief Check whether the request supplied an input.
    /// @param name The input name.
    /// @return `true` if entity_request::inputs has the name.
    [[nodiscard]] bool has_input(std::string_view name) const
    {
        return _inputs != nullptr && _inputs->find(name) != _inputs->end();
    }
 
    /// @brief A per-call input from the request.
    /// @tparam T One of `bool`, `std::int64_t`, `double`, `std::string`: the
    ///         type the input was given with.
    /// @param name The input name.
    /// @return The value.
    /// @throws std::invalid_argument If the request has no such input, or it
    ///         has another type (the message names the input).
    template <typename T>
    [[nodiscard]] T input(std::string_view name) const
    {
        const auto it = _inputs == nullptr ? input_map::const_iterator{} : _inputs->find(name);
        if (_inputs == nullptr || it == _inputs->end())
        {
            throw std::invalid_argument("input '" + std::string{name} + "' was not supplied");
        }
        const T* value = std::get_if<T>(&it->second);
        if (value == nullptr)
        {
            throw std::invalid_argument("input '" + std::string{name} + "' has another type");
        }
        return *value;
    }
 
    /// @brief A per-call input, or a fallback when the request has none.
    /// @tparam T The input type, as for input().
    /// @param name The input name.
    /// @param fallback Returned when the input was not supplied.
    /// @return The value, or @p fallback.
    /// @throws std::invalid_argument If the input has another type.
    template <typename T>
    [[nodiscard]] T input_or(std::string_view name, T fallback) const
    {
        return has_input(name) ? input<T>(name) : std::move(fallback);
    }
 
    /// @brief Access the random engine for this component.
    ///
    /// Seeded with the component's seed (entity::seed(key)), so the same
    /// draws reproduce the value. Use it with the dasmig-core functions,
    /// which give the same results on every platform:
    /// @code
    /// int age = dasmig::core::uniform_int(ctx.random(), 18, 65);
    /// const auto& title = dasmig::core::pick(ctx.random(), titles);
    /// bool lucky = dasmig::core::bernoulli(ctx.random(), 0.1);
    /// @endcode
    /// @return A reference to the per-component seeded engine.
    [[nodiscard]] core::rng& random() const
    {
        return _random;
    }
 
  private:
    // Private constructor, this is managed by the entity generator.
    generation_context() = default;
 
    // The value generated for a key, or nullptr.
    [[nodiscard]] const std::any* find_(const std::wstring& component_key) const
    {
        const auto it = std::ranges::find(_values, component_key,
                                          [](const auto& v) -> const std::wstring& { return *v.first; });
        return it == _values.end() ? nullptr : it->second;
    }
 
    // Already-generated component values: the key and the value, both owned
    // by the entity being generated (its entries never reallocate).
    std::vector<std::pair<const std::wstring*, const std::any*>> _values;
 
    // The request's inputs (owned by the request, which outlives the call).
    const input_map* _inputs{nullptr};
 
    // Per-component engine, reseeded before each component generates.
    mutable core::rng _random{0};
 
    // Allows entity generator to construct and populate contexts.
    friend class eg;
};
 
/// @brief Abstract base for entity components.
///
/// Implement this interface to define custom components that the entity
/// generator can produce. Each component has a unique key, generates typed
/// random values, and converts them to display strings.
/// @see generation_context, eg::add()
class component
{
  public:
    component() = default;                                ///< Default constructor.
    component(const component&) = default;                ///< Copyable.
    component& operator=(const component&) = default;     ///< Copyable.
    component(component&&) noexcept = default;            ///< Movable.
    component& operator=(component&&) noexcept = default; ///< Movable.
 
    /// @brief Virtual destructor for proper cleanup of derived classes.
    virtual ~component() = default;
 
    /// @brief Unique key identifying this component (e.g. `"name"`, `"age"`).
    /// @return The component key as a wide string.
    [[nodiscard]] virtual std::wstring key() const = 0;
 
    /// @brief Generate a random value for this component.
    /// @param ctx Context providing access to previously generated values
    ///            and a seeded random engine.
    /// @return The generated value wrapped in `std::any`.
    [[nodiscard]] virtual std::any generate(
        const generation_context& ctx) const = 0;
 
    /// @brief Convert a generated value to a displayable string.
    /// @param value The value previously returned by generate().
    /// @return A human-readable wide-string representation.
    /// @see default_to_string()
    [[nodiscard]] virtual std::wstring to_string(const std::any& value) const = 0;
 
    /// @brief Convert a generated value to JSON, for entity::to_json().
    ///
    /// The default writes `bool` as a boolean, integers as integers,
    /// `double` and `float` as numbers (non-finite ones as null),
    /// `std::wstring` and `std::string` as strings, and anything else as the
    /// string from to_string(). Override it to write a richer value: a
    /// json_value can hold arrays and objects.
    /// @param value The value previously returned by generate().
    /// @return The JSON value.
    [[nodiscard]] virtual json_value to_json(const std::any& value) const
    {
        return default_to_json(value, to_string(value));
    }
 
    /// @brief Display name of this component, used by entity::to_string().
    ///
    /// The key stays the identifier (lookups, seeds, JSON). A key with dots
    /// is a path: `L"identity.age"` is written as `{"identity":{"age":..}}`.
    /// @return The label; defaults to the key.
    [[nodiscard]] virtual std::wstring label() const { return key(); }
 
    /// @brief Keys of the components this one reads from the context.
    ///
    /// A request that selects this component also generates its dependencies
    /// (transitively) and orders them before it, whatever the registration
    /// order. If a dependency is skipped (weight roll or should_generate()),
    /// this component is skipped too. A dependency that is not registered, or
    /// a cycle, makes generation throw.
    /// @return The dependency keys; empty by default.
    [[nodiscard]] virtual std::vector<std::wstring> depends_on() const { return {}; }
 
    /// @brief Hash of the data this component draws from, for replay.
    ///
    /// A component that calls a generator with data returns that generator's
    /// `data_hash()`. entity::signature() combines the hashes of the components
    /// that ran, so a replay shows whether the data changed.
    /// @return The hash; 0 (no data) by default.
    [[nodiscard]] virtual std::uint64_t data_hash() const { return 0; }
 
    /// @brief Inclusion weight for this component (0.0 to 1.0).
    ///
    /// A value of 1.0 means always included; 0.5 means included roughly
    /// half the time. The generator may override this per-component at
    /// registration time via eg::add(comp, weight) or eg::weight().
    /// @return The inclusion probability.
    /// @see eg::weight()
    [[nodiscard]] virtual double weight() const { return 1.0; }
 
    /// @brief Validate a generated value.
    /// @param value The value to validate.
    /// @return `true` to accept, `false` to retry generation.
    /// @see eg::max_retries()
    [[nodiscard]] virtual bool validate([[maybe_unused]] const std::any& value) const
    {
        return true;
    }
 
    /// @brief Decide whether this component should be generated.
    ///
    /// Unlike weight() (probabilistic), this is logic-driven. Return
    /// `false` to skip generation entirely based on the current context.
    /// @param ctx Context with previously generated component values.
    /// @return `true` to generate, `false` to skip.
    [[nodiscard]] virtual bool should_generate(
        [[maybe_unused]] const generation_context& ctx) const
    {
        return true;
    }
 
  protected:
    /// @brief Default conversion covering common standard types.
    ///
    /// Handles `std::wstring`, `std::string` (UTF-8), `bool`, `float`,
    /// `double` and the integer types `int`, `long`, `long long` and their
    /// unsigned forms. Returns `"[?]"` for unrecognized types.
    /// @param value The value to convert.
    /// @return A wide-string representation.
    [[nodiscard]] static std::wstring default_to_string(const std::any& value)
    {
        if (value.type() == typeid(std::wstring))
        {
            return std::any_cast<std::wstring>(value);
        }
        if (value.type() == typeid(int))
        {
            return std::to_wstring(std::any_cast<int>(value));
        }
        if (value.type() == typeid(double))
        {
            return std::to_wstring(std::any_cast<double>(value));
        }
        if (value.type() == typeid(float))
        {
            return std::to_wstring(std::any_cast<float>(value));
        }
        if (value.type() == typeid(long))
        {
            return std::to_wstring(std::any_cast<long>(value));
        }
        if (value.type() == typeid(bool))
        {
            return std::any_cast<bool>(value) ? L"true" : L"false";
        }
        if (value.type() == typeid(std::string))
        {
            return core::from_utf8(std::any_cast<const std::string&>(value));
        }
        if (value.type() == typeid(long long))
        {
            return std::to_wstring(std::any_cast<long long>(value));
        }
        if (value.type() == typeid(unsigned))
        {
            return std::to_wstring(std::any_cast<unsigned>(value));
        }
        if (value.type() == typeid(unsigned long))
        {
            return std::to_wstring(std::any_cast<unsigned long>(value));
        }
        if (value.type() == typeid(unsigned long long))
        {
            return std::to_wstring(std::any_cast<unsigned long long>(value));
        }
 
        return L"[?]";
    }
 
    /// @brief Default JSON conversion used by to_json().
    /// @param value The value to convert.
    /// @param display Its to_string() form, used for unrecognized types.
    /// @return The JSON value.
    [[nodiscard]] static json_value default_to_json(const std::any& value,
                                                    const std::wstring& display)
    {
        const auto& type = value.type();
        if (type == typeid(bool)) return std::any_cast<bool>(value);
        if (type == typeid(int)) return std::int64_t{std::any_cast<int>(value)};
        if (type == typeid(long)) return std::int64_t{std::any_cast<long>(value)};
        if (type == typeid(long long)) return std::int64_t{std::any_cast<long long>(value)};
        if (type == typeid(unsigned)) return std::int64_t{std::any_cast<unsigned>(value)};
        // Larger unsigned values stay exact as text rather than wrapping.
        if (type == typeid(unsigned long) || type == typeid(unsigned long long))
        {
            const auto n = type == typeid(unsigned long)
                               ? static_cast<unsigned long long>(std::any_cast<unsigned long>(value))
                               : std::any_cast<unsigned long long>(value);
            if (n <= static_cast<unsigned long long>(std::numeric_limits<std::int64_t>::max()))
                return static_cast<std::int64_t>(n);
            return std::to_string(n);
        }
        if (type == typeid(double) || type == typeid(float))
        {
            const double d = type == typeid(double) ? std::any_cast<double>(value)
                                                    : double{std::any_cast<float>(value)};
            if (!std::isfinite(d)) return nullptr;
            return d;
        }
        if (type == typeid(std::wstring)) return core::to_utf8(std::any_cast<std::wstring>(value));
        if (type == typeid(std::string)) return std::any_cast<std::string>(value);
        return core::to_utf8(display);
    }
};
 
/// @name Generic Components
/// @brief Reusable component templates for common patterns.
/// @{
 
/// @brief Tag type indicating that generic components should use default_to_string().
struct use_default_formatter {};
 
/// @brief Component that always returns a fixed value.
/// @tparam T The value type.
/// @tparam Formatter Optional callable for custom string conversion
///                    (defaults to use_default_formatter).
template <typename T, typename Formatter = use_default_formatter>
class constant_component : public component
{
  public:
    /// @brief Construct a constant component.
    /// @param key Unique component key.
    /// @param value The fixed value to always return.
    /// @param fmt Optional custom formatter.
    explicit constant_component(std::wstring key, T value,
                                Formatter fmt = {})
        : _key{std::move(key)}, _value{std::move(value)},
          _fmt{std::move(fmt)} {}
 
    [[nodiscard]] std::wstring key() const override { return _key; }
 
    [[nodiscard]] std::any generate(
        const generation_context& /*ctx*/) const override
    {
        return _value;
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        if constexpr (std::is_same_v<Formatter, use_default_formatter>)
            return default_to_string(value);
        else
            return _fmt(std::any_cast<T>(value));
    }
 
  private:
    std::wstring _key;
    T _value;
    Formatter _fmt;
};
 
/// @brief Component that picks uniformly at random from a list of values.
/// @tparam T The value type.
/// @tparam Formatter Optional callable for custom string conversion.
template <typename T, typename Formatter = use_default_formatter>
class choice_component : public component
{
  public:
    /// @brief Construct a choice component.
    /// @param key Unique component key.
    /// @param choices Non-empty list of values to choose from.
    /// @param fmt Optional custom formatter.
    /// @throws std::invalid_argument If @p choices is empty.
    explicit choice_component(std::wstring key, std::vector<T> choices,
                              Formatter fmt = {})
        : _key{std::move(key)}, _choices{std::move(choices)},
          _fmt{std::move(fmt)}
    {
        if (_choices.empty())
            throw std::invalid_argument("choices must not be empty");
    }
 
    [[nodiscard]] std::wstring key() const override { return _key; }
 
    [[nodiscard]] std::any generate(
        const generation_context& ctx) const override
    {
        return core::pick(ctx.random(), _choices);
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        if constexpr (std::is_same_v<Formatter, use_default_formatter>)
            return default_to_string(value);
        else
            return _fmt(std::any_cast<T>(value));
    }
 
  private:
    std::wstring _key;
    std::vector<T> _choices;
    Formatter _fmt;
};
 
/// @brief Component that generates a uniform random value: integers in
///        [lo, hi], floating-point values in [lo, hi).
/// @tparam T An integer type (not `bool`) or a floating-point type.
/// @tparam Formatter Optional callable for custom string conversion.
template <typename T, typename Formatter = use_default_formatter>
    requires(std::integral<T> && !std::same_as<T, bool>) || std::floating_point<T>
class range_component : public component
{
  public:
    /// @brief Construct a range component.
    /// @param key Unique component key.
    /// @param lo Lower bound (inclusive).
    /// @param hi Upper bound (inclusive).
    /// @param fmt Optional custom formatter.
    explicit range_component(std::wstring key, T lo, T hi, // NOLINT(bugprone-easily-swappable-parameters)
                             Formatter fmt = {})
        : _key{std::move(key)}, _lo{lo}, _hi{hi}, _fmt{std::move(fmt)} {}
 
    [[nodiscard]] std::wstring key() const override { return _key; }
 
    [[nodiscard]] std::any generate(
        const generation_context& ctx) const override
    {
        if constexpr (std::floating_point<T>)
        {
            auto v = static_cast<T>(core::uniform_real(ctx.random(), static_cast<double>(_lo),
                                                       static_cast<double>(_hi)));
            // Narrowing to float can round up to hi; keep the range half-open.
            if (v >= _hi && _hi > _lo) v = std::nextafter(_hi, _lo);
            return v;
        }
        else
        {
            return core::uniform_int(ctx.random(), _lo, _hi);
        }
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        if constexpr (std::is_same_v<Formatter, use_default_formatter>)
            return default_to_string(value);
        else
            return _fmt(std::any_cast<T>(value));
    }
 
  private:
    std::wstring _key;
    T _lo;
    T _hi;
    Formatter _fmt;
};
 
/// @brief Component that wraps a callable for one-off or computed values.
///
/// Avoids subclassing component entirely. The callable receives a
/// generation_context and returns a value of type @p T.
/// @tparam T The return type of the callable.
/// @tparam GenFn Callable type taking `const generation_context&`.
/// @tparam Formatter Optional callable for custom string conversion.
template <typename T, typename GenFn, typename Formatter = use_default_formatter>
class callback_component : public component
{
  public:
    /// @brief Construct a callback component.
    /// @param key Unique component key.
    /// @param fn Callable invoked during generation.
    /// @param fmt Optional custom formatter.
    explicit callback_component(std::wstring key, GenFn fn,
                                Formatter fmt = {})
        : _key{std::move(key)}, _fn{std::move(fn)}, _fmt{std::move(fmt)} {}
 
    [[nodiscard]] std::wstring key() const override { return _key; }
 
    [[nodiscard]] std::any generate(
        const generation_context& ctx) const override
    {
        return _fn(ctx);
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        if constexpr (std::is_same_v<Formatter, use_default_formatter>)
            return default_to_string(value);
        else
            return _fmt(std::any_cast<T>(value));
    }
 
  private:
    std::wstring _key;
    GenFn _fn;
    Formatter _fmt;
};
 
/// @brief Deduction guide for callback_component.
///
/// Deduces @p T from the return type of @p GenFn so users don't need
/// to spell out the lambda type explicitly.
template <typename GenFn, typename Formatter = use_default_formatter>
callback_component(std::wstring, GenFn, Formatter = {})
    -> callback_component<
           std::invoke_result_t<GenFn, const generation_context&>,
           GenFn, Formatter>;
 
/// @brief A component built from a callable, with every optional hook set by
///        a chained call; see field().
///
/// The setters work on a temporary and return it, so a field is written in
/// one expression and passed to eg::add():
/// @code
/// gen.add(dasmig::field(L"identity.age", [](const dasmig::generation_context& ctx) {
///             return ctx.get<birth>(L"birth").age;
///         })
///         .label(L"Age")
///         .depends_on({L"birth"}));
/// @endcode
/// @tparam T The value type the callable returns.
template <typename T>
class field_component final : public component
{
  public:
    /// @brief The callable that produces the value.
    using generator = std::function<T(const generation_context&)>;
 
    /// @brief Construct a field.
    /// @param key Unique component key (dots make a path in the JSON).
    /// @param fn Callable invoked during generation.
    field_component(std::wstring key, generator fn) : _key{std::move(key)}, _fn{std::move(fn)} {}
 
    /// @brief Set the display label (default: the key).
    [[nodiscard]] field_component label(std::wstring text) &&
    {
        _label = std::move(text);
        return std::move(*this);
    }
 
    /// @brief Declare the components this one reads; see component::depends_on().
    [[nodiscard]] field_component depends_on(std::vector<std::wstring> keys) &&
    {
        _depends = std::move(keys);
        return std::move(*this);
    }
 
    /// @brief Set how the value is shown by to_string().
    [[nodiscard]] field_component format(std::function<std::wstring(const T&)> fn) &&
    {
        _format = std::move(fn);
        return std::move(*this);
    }
 
    /// @brief Set how the value is written by to_json().
    [[nodiscard]] field_component json(std::function<json_value(const T&)> fn) &&
    {
        _json = std::move(fn);
        return std::move(*this);
    }
 
    /// @brief Set the inclusion weight (0.0 to 1.0); see component::weight().
    [[nodiscard]] field_component weight(double inclusion) &&
    {
        _weight = inclusion;
        return std::move(*this);
    }
 
    /// @brief Generate the field only when the callable returns true;
    ///        see component::should_generate().
    [[nodiscard]] field_component when(std::function<bool(const generation_context&)> fn) &&
    {
        _when = std::move(fn);
        return std::move(*this);
    }
 
    /// @brief Accept only values the callable accepts; see component::validate().
    [[nodiscard]] field_component validate(std::function<bool(const T&)> fn) &&
    {
        _validate = std::move(fn);
        return std::move(*this);
    }
 
    /// @brief Set the hash of the data the field draws from; see component::data_hash().
    [[nodiscard]] field_component data_hash(std::uint64_t hash) &&
    {
        _data_hash = hash;
        return std::move(*this);
    }
 
    [[nodiscard]] std::wstring key() const override { return _key; }
    [[nodiscard]] std::wstring label() const override { return _label.value_or(_key); }
    [[nodiscard]] std::vector<std::wstring> depends_on() const override { return _depends; }
    [[nodiscard]] std::uint64_t data_hash() const override { return _data_hash; }
    [[nodiscard]] double weight() const override { return _weight; }
 
    [[nodiscard]] std::any generate(const generation_context& ctx) const override
    {
        return std::any{_fn(ctx)};
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        return _format ? _format(std::any_cast<const T&>(value)) : default_to_string(value);
    }
 
    [[nodiscard]] json_value to_json(const std::any& value) const override
    {
        return _json ? _json(std::any_cast<const T&>(value))
                     : default_to_json(value, to_string(value));
    }
 
    [[nodiscard]] bool validate(const std::any& value) const override
    {
        return !_validate || _validate(std::any_cast<const T&>(value));
    }
 
    [[nodiscard]] bool should_generate(const generation_context& ctx) const override
    {
        return !_when || _when(ctx);
    }
 
  private:
    std::wstring _key;
    generator _fn;
    std::optional<std::wstring> _label;
    std::vector<std::wstring> _depends;
    std::function<std::wstring(const T&)> _format;
    std::function<json_value(const T&)> _json;
    std::function<bool(const generation_context&)> _when;
    std::function<bool(const T&)> _validate;
    double _weight{1.0};
    std::uint64_t _data_hash{0};
};
 
/// @brief Build a field from a callable; T is what the callable returns.
/// @param key Unique component key.
/// @param fn Callable taking `const generation_context&`.
/// @return The field, to be configured with chained calls and added with eg::add().
/// @see field_component
template <typename Fn>
[[nodiscard]] auto field(std::wstring key, Fn fn)
{
    return field_component<std::invoke_result_t<Fn, const generation_context&>>{
        std::move(key), std::move(fn)};
}
 
/// @brief Component that picks from a list of values using per-option weights.
///
/// Weights are relative (they don't need to sum to 1.0). A weight of 0
/// means the option is never selected. The choice is dasmig-core's weighted
/// choice (the same algorithm as core::weighted_table), built once.
/// @tparam T The value type.
/// @tparam Formatter Optional callable for custom string conversion.
template <typename T, typename Formatter = use_default_formatter>
class weighted_choice_component : public component
{
  public:
    /// @brief A value–weight pair for weighted selection.
    struct option
    {
        T value;         ///< The selectable value.
        double weight;   ///< Relative selection weight (must be >= 0).
    };
 
    /// @brief Construct a weighted choice component.
    /// @param key Unique component key.
    /// @param options Non-empty list of value–weight pairs. At least one
    ///                must have a positive weight.
    /// @param fmt Optional custom formatter.
    /// @throws std::invalid_argument If @p options is empty, a weight is
    ///         negative or not finite, or all weights are zero.
    explicit weighted_choice_component(std::wstring key,
                                       std::vector<option> options,
                                       Formatter fmt = {})
        : _key{std::move(key)}, _options{std::move(options)},
          _fmt{std::move(fmt)}, _dist{weights_of(_options)}
    {
    }
 
    [[nodiscard]] std::wstring key() const override { return _key; }
 
    [[nodiscard]] std::any generate(
        const generation_context& ctx) const override
    {
        return _options[_dist(ctx.random())].value;
    }
 
    [[nodiscard]] std::wstring to_string(const std::any& value) const override
    {
        if constexpr (std::is_same_v<Formatter, use_default_formatter>)
            return default_to_string(value);
        else
            return _fmt(std::any_cast<T>(value));
    }
 
  private:
    // Checked here so the messages name the problem before core::discrete
    // sees the weights.
    static std::vector<double> weights_of(const std::vector<option>& options)
    {
        if (options.empty())
            throw std::invalid_argument("options must not be empty");
        if (!std::ranges::all_of(options, [](const auto& o) {
                return std::isfinite(o.weight) && o.weight >= 0.0;
            }))
            throw std::invalid_argument("option weights must be finite and non-negative");
        if (!std::ranges::any_of(options, [](const auto& o) { return o.weight > 0.0; }))
            throw std::invalid_argument(
                "at least one option must have a positive weight");
        std::vector<double> weights;
        weights.reserve(options.size());
        std::ranges::transform(options, std::back_inserter(weights), &option::weight);
        return weights;
    }
 
    std::wstring _key;
    std::vector<option> _options;
    Formatter _fmt;
    core::discrete _dist;
};
 
/// @}
 
/// @brief A generated entity holding component values in registration order.
///
/// Entities are produced by eg::generate and provide typed access to
/// component values, seed signatures for replay, and serialization.
/// @see eg::generate
class entity
{
  public:
    /// @brief Typed retrieval of a component value by key.
    /// @tparam T The expected type of the stored value.
    /// @param component_key The component key to retrieve.
    /// @return The value cast to @p T.
    /// @throws std::out_of_range If the key is not present.
    /// @throws std::bad_any_cast If @p T does not match the stored type.
    template <typename T>
    [[nodiscard]] T get(const std::wstring& component_key) const
    {
        return std::any_cast<T>(find_value(component_key));
    }
 
    /// @brief Type-erased retrieval of a component value by key.
    /// @param component_key The component key to retrieve.
    /// @return A const reference to the stored `std::any`.
    /// @throws std::out_of_range If the key is not present.
    [[nodiscard]] const std::any& get_any(const std::wstring& component_key) const
    {
        return find_value(component_key);
    }
 
    /// @brief Check if a component value exists by key.
    /// @param component_key The component key to look up.
    /// @return `true` if the entity contains a value for the key.
    [[nodiscard]] bool has(const std::wstring& component_key) const
    {
        return std::ranges::any_of(_entries, [&component_key](const auto& e) {
            return e.key == component_key;
        });
    }
 
    /// @brief Retrieve the random seed used to generate a specific component.
    /// @param component_key The component key.
    /// @return The per-component seed for replay.
    /// @throws std::out_of_range If the key is not present.
    [[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;
    }
 
    /// @brief Retrieve the random seed used to generate this entity.
    ///
    /// eg::generate(request, seed()) with the same request and setup reproduces
    /// the entity:
    /// it is the call seed, or the seed of the attempt the entity validator
    /// accepted. Component @c k drew from
    /// `core::rng{seed()}.split(core::to_utf8(k))`.
    /// @return The entity-level seed.
    [[nodiscard]] std::uint64_t seed() const
    {
        return _seed;
    }
 
    /// @brief The seed and the data this entity was generated from, in the
    ///        format every dasmig result uses.
    /// @return The replay signature. `data` combines the request's inputs and
    ///         the component::data_hash() of every component that ran; it is
    ///         0 when there are none, as for a generator without data.
    [[nodiscard]] core::seed_signature signature() const
    {
        return {.seed = _seed, .data = _data};
    }
 
    /// @brief Write this entity as a JSON object
    ///        `{"components":{"key":value,…},"signature":{…}}`, components
    ///        in generation order, values from component::to_json().
    ///
    /// A key with dots is a path: `identity.name` and `identity.age` are
    /// written as members of one `identity` object, placed where its first
    /// member comes.
    /// @param w Writer positioned where a value is allowed.
    void to_json(core::json_writer& w) const
    {
        json_value::object root;
        for (const auto& e : _entries) insert_path(root, core::to_utf8(e.key), e.json);
        w.begin_object().key("components");
        json_value{std::move(root)}.write(w);
        w.key("signature");
        signature().to_json(w);
        w.end_object();
    }
 
    /// @brief This entity as a JSON document.
    /// @return Compact JSON.
    [[nodiscard]] std::string to_json() const
    {
        core::json_writer w;
        to_json(w);
        return w.str();
    }
 
    /// @brief Get all component keys present in this entity, in generation order.
    /// @return A vector of component keys.
    [[nodiscard]] std::vector<std::wstring> keys() const
    {
        std::vector<std::wstring> result;
        result.reserve(_entries.size());
        std::ranges::transform(_entries, std::back_inserter(result), &entry::key);
        return result;
    }
 
    /// @brief Return component values as a map of key to display string.
    /// @return An ordered map of key → formatted value.
    [[nodiscard]] std::map<std::wstring, std::wstring> to_map() const
    {
        std::map<std::wstring, std::wstring> result;
        for (const auto& e : _entries)
        {
            result.emplace(e.key, e.display);
        }
        return result;
    }
 
    /// @brief Number of component values in this entity.
    [[nodiscard]] std::size_t size() const { return _entries.size(); }
 
    /// @brief Check if the entity has no component values.
    [[nodiscard]] bool empty() const { return _entries.empty(); }
 
    /// @brief Convert all component values to a single formatted string.
    ///
    /// Each entry is rendered as `"label: display"` separated by two spaces.
    /// @return The formatted string, or empty if the entity is empty.
    [[nodiscard]] std::wstring to_string() const
    {
        // A plain loop: std::ranges::fold_left_first is missing from libc++
        // 18, Apple's libc++ and Emscripten.
        std::wstring result;
        for (const auto& e : _entries)
        {
            if (!result.empty()) result += L"  ";
            result += e.label + L": " + e.display;
        }
        return result;
    }
 
    /// @brief Stream all component values in generation order.
    friend std::wostream& operator<<(std::wostream& wos, const entity& e)
    {
        return wos << e.to_string();
    }
 
  private:
    // A single component entry in generation order.
    struct entry
    {
        std::wstring key;
        std::wstring label;
        std::any value;
        std::wstring display;
        std::uint64_t seed;
        json_value json;
    };
 
    // Private constructor, this is mostly a helper class to the entity
    // generator, not the intended API.
    entity() = default;
 
    // Find a component value by key.
    [[nodiscard]] const std::any& find_value(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->value;
    }
 
    // Add a value at a dotted path, creating the objects on the way.
    // Registration rejects keys that would collide, so a path is never both
    // a value and an object.
    static void insert_path(json_value::object& root, std::string_view path, const json_value& value)
    {
        json_value::object* level = &root;
        for (auto dot = path.find('.'); dot != std::string_view::npos; dot = path.find('.'))
        {
            const std::string_view name = path.substr(0, dot);
            path.remove_prefix(dot + 1);
            auto it = std::ranges::find(*level, name, &json_value::object::value_type::first);
            if (it == level->end())
            {
                level->emplace_back(std::string{name}, json_value::object{});
                it = std::prev(level->end());
            }
            level = it->second.get_object();
            if (level == nullptr) throw std::logic_error("component keys collide in the JSON");
        }
        level->emplace_back(std::string{path}, value);
    }
 
    // Component entries in generation order.
    std::vector<entry> _entries;
 
    // Seed used to generate this entity.
    std::uint64_t _seed{0};
 
    // Hash of the inputs and of the data the components drew from (0: none).
    std::uint64_t _data{0};
 
    // Allows entity generator to construct entities.
    friend class eg;
};
 
/// @brief Observer interface for hooking into generation lifecycle events.
///
/// Override only the methods you care about; all default to no-ops.
/// Multiple observers can be attached to a generator via eg::add_observer().
/// @see eg::add_observer(), dasmig::ext::stats_observer
class generation_observer
{
  public:
    generation_observer() = default;                                          ///< Default constructor.
    generation_observer(const generation_observer&) = default;                ///< Copyable.
    generation_observer& operator=(const generation_observer&) = default;     ///< Copyable.
    generation_observer(generation_observer&&) noexcept = default;            ///< Movable.
    generation_observer& operator=(generation_observer&&) noexcept = default; ///< Movable.
 
    /// @brief Virtual destructor.
    virtual ~generation_observer() = default;
 
    /// @name Entity Lifecycle
    /// @{
 
    /// @brief Called before an entity is generated.
    virtual void on_before_generate() {}
    /// @brief Called after an entity is successfully generated.
    /// @param e The generated entity.
    virtual void on_after_generate([[maybe_unused]] const entity& e) {}
 
    /// @}
    /// @name Component Generation
    /// @{
 
    /// @brief Called before a component is generated.
    /// @param key The component key about to be generated.
    virtual void on_before_component([[maybe_unused]] const std::wstring& key) {}
    /// @brief Called after a component is successfully generated.
    /// @param key The component key.
    /// @param value The generated value.
    virtual void on_after_component([[maybe_unused]] const std::wstring& key,
                                    [[maybe_unused]] const std::any& value) {}
 
    /// @}
    /// @name Component Skip
    /// @{
 
    /// @brief Called when a component is skipped (weight roll or conditional exclusion).
    /// @param key The skipped component key.
    virtual void on_skip([[maybe_unused]] const std::wstring& key) {}
 
    /// @}
    /// @name Component Validation
    /// @{
 
    /// @brief Called before a component validation retry.
    /// @param key The component key being retried.
    /// @param attempt The retry attempt number (1-based).
    virtual void on_before_retry([[maybe_unused]] const std::wstring& key,
                                 [[maybe_unused]] std::size_t attempt) {}
    /// @brief Called after a component validation retry.
    /// @param key The component key.
    /// @param attempt The retry attempt number.
    /// @param value The newly generated value.
    virtual void on_after_retry([[maybe_unused]] const std::wstring& key,
                                [[maybe_unused]] std::size_t attempt,
                                [[maybe_unused]] const std::any& value) {}
 
    /// @brief Called when component validation is exhausted (precedes exception).
    /// @param key The failed component key.
    virtual void on_component_fail([[maybe_unused]] const std::wstring& key) {}
 
    /// @}
    /// @name Entity Validation
    /// @{
 
    /// @brief Called before an entity validation retry.
    /// @param attempt The entity retry attempt number (1-based).
    virtual void on_before_entity_retry([[maybe_unused]] std::size_t attempt) {}
    /// @brief Called after an entity validation retry.
    /// @param attempt The entity retry attempt number.
    virtual void on_after_entity_retry([[maybe_unused]] std::size_t attempt) {}
 
    /// @brief Called when entity validation is exhausted (precedes exception).
    virtual void on_entity_fail() {}
 
    /// @}
    /// @name Component Registration
    /// @{
 
    /// @brief Called before a component is registered.
    /// @param key The component key being added.
    virtual void on_before_add([[maybe_unused]] const std::wstring& key) {}
    /// @brief Called after a component is registered.
    /// @param key The component key that was added.
    virtual void on_after_add([[maybe_unused]] const std::wstring& key) {}
 
    /// @brief Called before a component is removed.
    /// @param key The component key being removed.
    virtual void on_before_remove([[maybe_unused]] const std::wstring& key) {}
    /// @brief Called after a component is removed.
    /// @param key The component key that was removed.
    virtual void on_after_remove([[maybe_unused]] const std::wstring& key) {}
 
    /// @}
};
 
/// @brief Per-call entity generation and selection options.
///
/// Defaults select all registered components, generate one entity in a batch,
/// and accept entities without an entity-level validator. Component validation,
/// weights, conditions, registration order and the generator's retry policy
/// still apply. Replay requires the same request and instance setup.
struct entity_request
{
    /// @brief Optional key subset; absent selects all, an empty vector selects none.
    /// Unknown keys are skipped and registration order is preserved.
    std::optional<std::vector<std::wstring>> component_keys{};
 
    /// @brief Optional registered group name, mutually exclusive with component_keys.
    /// Required by eg::generate_group; also supported by the other generation methods.
    std::optional<std::wstring> group{};
 
    /// @brief Number of entities for batch methods (ignored by single-entity methods).
    std::size_t count{1};
 
    /// @brief Optional entity validator; false retries the whole entity.
    /// Concurrent batches require a thread-safe callable and captured state.
    std::function<bool(const entity&)> validator{};
 
    /// @brief Per-call inputs for the components (a country, a reference
    /// date, a forced sex, ...), read with generation_context::input().
    /// They are part of the entity's replay signature. Give strings as
    /// `std::string{"BR"}`; a bare literal also works with C++23 compilers.
    input_map inputs{};
};
 
/// @brief The entity generator — produces entities with configurable components.
///
/// Components are registered by implementing the component interface and
/// adding them to the generator. Components are generated in registration
/// order, allowing later components to access earlier ones via context.
/// @see component, entity, entity_request, generation_context
class eg
{
  public:
    /// @brief Default constructor creates an empty generator.
    eg() = default;
 
    eg(const eg&) = delete;            ///< Not copyable.
    eg& operator=(const eg&) = delete; ///< Not copyable.
    eg(eg&&) noexcept = default;            ///< Move constructor.
    eg& operator=(eg&&) noexcept = default; ///< Move assignment.
    ~eg() = default;                   ///< Default destructor.
 
    /// @brief Access the global singleton instance.
    ///
    /// For multi-threaded use, prefer creating independent eg instances.
    /// @return A reference to the singleton.
    static eg& instance()
    {
        static eg instance;
        return instance;
    }
 
    /// @name Registration
    /// @{
 
    /// @brief Register a component.
    ///
    /// Takes ownership of the component. If a component with the same key
    /// already exists, it will be replaced. Components are generated in the
    /// order they are registered.
    /// @param comp The component to register (moved).
    /// @return `*this` for chaining.
    /// @throws std::invalid_argument If the key has an empty path segment
    ///         (`a..b`, `.a`, `a.`), or would be both a value and the parent of
    ///         another key (`a` with `a.b`).
    eg& add(std::unique_ptr<component> comp)
    {
        const auto key = comp->key();
        check_key(key);
        notify(&generation_observer::on_before_add, key);
 
        auto it = std::ranges::find(_components, key, &component_entry::key);
 
        if (it != _components.end())
        {
            it->comp = std::move(comp);
        }
        else
        {
            _components.push_back({.key = key, .comp = std::move(comp)});
        }
 
        notify(&generation_observer::on_after_add, key);
        return *this;
    }
 
    /// @brief Register a field built with field().
    /// @tparam T The field's value type.
    /// @param f The field (moved).
    /// @return `*this` for chaining.
    /// @throws std::invalid_argument As add(std::unique_ptr<component>).
    template <typename T>
    eg& add(field_component<T> f)
    {
        return add(std::make_unique<field_component<T>>(std::move(f)));
    }
 
    /// @brief Register the components a recipe declares.
    ///
    /// A recipe is a tab-separated file with a header line and one component
    /// per row, so a component that only draws from data is written as data
    /// instead of code (see add_recipe_from_string() for the columns). The
    /// components are the ones the code makes with field(): the same
    /// dependencies, ordering, weights and replay. An invalid row throws and
    /// adds nothing.
    ///
    /// @param path The recipe file.
    /// @return `*this` for chaining.
    /// @throws core::tsv_error If the file cannot be read or a row is invalid.
    /// @throws std::invalid_argument As add(std::unique_ptr<component>).
    eg& add_recipe(const std::filesystem::path& path)
    {
        return add_recipe_(core::tsv_document::load(path));
    }
 
    /// @brief Register the components a recipe in text declares.
    ///
    /// Columns (the header names them, in any order):
    ///
    /// | Column | | Meaning |
    /// |---|---|---|
    /// | `key` | required | The component key; dots make a path in the JSON |
    /// | `kind` | required | `constant`, `choice`, `weighted`, `int` or `real` |
    /// | `values` | required | What the kind draws from, below |
    /// | `label` | optional | Display name; the key by default |
    /// | `depends_on` | optional | Keys this component follows, separated by `;` |
    /// | `weight` | optional | Inclusion probability, 0 to 1; 1 by default |
    ///
    /// The kinds: `constant` gives `values` as text; `choice` picks uniformly
    /// from `a|b|c`; `weighted` picks from `a:3|b:1` (a value and its
    /// relative weight, split at the last colon); `int` draws an integer from
    /// `lo..hi` (both included); `real` draws a number from `lo..hi` (`hi`
    /// excluded). Text kinds give strings in the JSON, `int` and `real` give
    /// numbers. Items are not trimmed. A component with the key of an
    /// existing one replaces it. The recipe's rows are part of the entity's
    /// replay signature.
    ///
    /// @param text UTF-8 recipe text.
    /// @param source Name used in errors.
    /// @return `*this` for chaining.
    /// @throws core::tsv_error If the text is malformed or a row is invalid
    ///         (an unknown kind, a bad range or weight, a repeated key).
    /// @throws std::invalid_argument As add(std::unique_ptr<component>).
    eg& add_recipe_from_string(std::string_view text, std::string source = "recipe")
    {
        return add_recipe_(core::tsv_document::parse(text, std::move(source)));
    }
 
    /// @brief Register a component with a weight override.
    ///
    /// The override takes precedence over the component's own weight() method.
    /// @param comp The component to register (moved).
    /// @param weight_override Inclusion probability override (0.0–1.0).
    /// @return `*this` for chaining.
    eg& add(std::unique_ptr<component> comp, double weight_override)
    {
        const auto key = comp->key();
        add(std::move(comp));
        _weight_overrides[key] = weight_override;
        return *this;
    }
 
    /// @brief Set or update the weight override for a registered component.
    /// @param component_key The component key.
    /// @param weight_value New inclusion probability (0.0–1.0).
    /// @return `*this` for chaining.
    /// @throws std::out_of_range If the component is not registered.
    eg& weight(const std::wstring& component_key, double weight_value)
    {
        if (!has(component_key))
        {
            throw std::out_of_range("component not found");
        }
 
        _weight_overrides[component_key] = weight_value;
        return *this;
    }
 
    /// @brief Remove a registered component by key.
    /// @param component_key The component key to remove.
    /// @return `*this` for chaining.
    eg& remove(const std::wstring& component_key)
    {
        notify(&generation_observer::on_before_remove, component_key);
 
        std::erase_if(_components, [&component_key](const auto& entry) {
            return entry.key == component_key;
        });
        _weight_overrides.erase(component_key);
 
        notify(&generation_observer::on_after_remove, component_key);
        return *this;
    }
 
    /// @brief Check if a component is registered by key.
    /// @param component_key The component key to look up.
    /// @return `true` if a component with the key exists.
    [[nodiscard]] bool has(const std::wstring& component_key) const
    {
        return std::ranges::any_of(_components, [&component_key](const auto& entry) {
            return entry.key == component_key;
        });
    }
 
    /// @brief Remove all registered components, weight overrides, and groups.
    /// @return `*this` for chaining.
    eg& clear()
    {
        _components.clear();
        _weight_overrides.clear();
        _groups.clear();
        return *this;
    }
 
    /// @brief Return the number of registered components.
    [[nodiscard]] std::size_t size() const { return _components.size(); }
 
    /// @brief Return all registered component keys in registration order.
    /// @return A vector of component keys.
    [[nodiscard]] std::vector<std::wstring> component_keys() const
    {
        std::vector<std::wstring> keys;
        keys.reserve(_components.size());
        std::ranges::transform(_components, std::back_inserter(keys),
            &component_entry::key);
        return keys;
    }
 
    /// @}
    /// @name Validation
    /// @{
 
    /// @brief Set the maximum number of retries for validation (default 10).
    ///
    /// Applies to both component-level and entity-level validation.
    /// @param retries The maximum retry count.
    /// @return `*this` for chaining.
    eg& max_retries(std::size_t retries)
    {
        _max_retries = retries;
        return *this;
    }
 
    /// @}
    /// @name Observers
    /// @{
 
    /// @brief Add an observer to receive generation lifecycle callbacks.
    /// @param obs The observer (shared ownership).
    /// @return `*this` for chaining.
    /// @see generation_observer
    eg& add_observer(std::shared_ptr<generation_observer> obs)
    {
        _observers.push_back(std::move(obs));
        return *this;
    }
 
    /// @brief Remove a specific observer by identity.
    /// @param obs The observer to remove.
    /// @return `*this` for chaining.
    eg& remove_observer(const std::shared_ptr<generation_observer>& obs)
    {
        std::erase(_observers, obs);
        return *this;
    }
 
    /// @brief Remove all observers.
    /// @return `*this` for chaining.
    eg& clear_observers()
    {
        _observers.clear();
        return *this;
    }
 
    /// @}
    /// @name Generation
    /// @{
 
    /// @brief Generate an entity using per-call options.
    ///
    /// Draws a call seed from the generator's engine.
    /// @param request Selection and entity validation options.
    /// @return The generated entity.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    [[nodiscard]] entity generate(const entity_request& request)
    {
        const auto refs = resolve_components(request);
        return generate_seeded(refs, _engine(), request);
    }
 
    /// @brief Generate an entity using a request and a seed.
    ///
    /// The same seed and components give the same entity on every compiler
    /// and platform. Each component draws from a stream split from the seed
    /// by its key, so adding or removing a component does not change the
    /// others.
    /// @param request Selection and entity validation options.
    /// @param call_seed Seed for reproducible results; does not advance the internal engine.
    /// @return The generated entity.
    /// @throws std::runtime_error If validation is exhausted.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    [[nodiscard]] entity generate(const entity_request& request,
                                  std::uint64_t call_seed) const
    {
        return generate_seeded(resolve_components(request), call_seed, request);
    }
 
    /// @}
    /// @name Batch Generation
    /// @{
 
    /// @brief Generate request.count entities using per-call options.
    ///
    /// Draws one call seed from the generator's engine for the batch.
    /// @param request Selection, batch count and entity validation options.
    /// @return A vector of generated entities.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] std::vector<entity> generate_batch(const entity_request& request)
    {
        const auto refs = resolve_components(request);
        return generate_batch_seeded(refs, request, _engine());
    }
 
    /// @brief Generate multiple entities using a seed.
    ///
    /// Entity @c i uses `core::item_seed(call_seed, i)` as its call seed, so
    /// the result equals generate_batch_async(request, call_seed) and each
    /// entity replays with generate(request, e.seed()). Since 4.1.0 this is
    /// the same seed derivation as every other library's batch; before, entity
    /// @c i used the @c i-th value of `core::rng{call_seed}.split("batch")`.
    /// @param request Selection, batch count and entity validation options.
    /// @param call_seed Seed for reproducible results.
    /// @return A vector of generated entities.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] std::vector<entity> generate_batch(
        const entity_request& request, std::uint64_t call_seed) const
    {
        return generate_batch_seeded(resolve_components(request), request, call_seed);
    }
 
    /// @brief Generate a batch described by core::batch_options, from a seed
    ///        drawn from the generator's engine.
    ///
    /// Uses `options.count` (the request's `count` is ignored here; it stays
    /// for generate_batch(request) until the next major version).
    /// @param request Selection and entity validation options.
    /// @param options Count, first index, threads and uniqueness.
    /// @return The entities, in index order.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] std::vector<entity> generate_batch(const entity_request& request,
                                                     const core::batch_options& options)
    {
        return generate_batch(request, options, _engine());
    }
 
    /// @brief Generate a batch described by core::batch_options, deterministically.
    ///
    /// Entity @c i is exactly `generate(request, core::item_seed(batch_seed,
    /// options.first + i))`, for any `options.threads`. With more than one
    /// thread, components, observers and the request's validator (including
    /// captured state) must be thread-safe.
    /// @param request Selection and entity validation options.
    /// @param options Count, first index, threads and uniqueness (see
    ///        core::unique_rule, made for `entity`).
    /// @param batch_seed Seed of the whole batch.
    /// @return The entities, in index order.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted,
    ///         or a unique batch runs out of attempts.
    [[nodiscard]] std::vector<entity> generate_batch(const entity_request& request,
                                                     const core::batch_options& options,
                                                     std::uint64_t batch_seed) const
    {
        const auto refs = resolve_components(request);
        return core::run_batch(options, batch_seed, [&](std::uint64_t item_seed)
                               { return generate_seeded(refs, item_seed, request); });
    }
 
    /// @brief Stream a batch of entities to a sink without holding the batch.
    ///
    /// Generates the same entities as generate_batch(request, options,
    /// batch_seed) and calls `sink(index, entity&)` in index order on the
    /// calling thread; `index` includes `options.first`.
    /// @tparam Sink Callable taking `(std::uint64_t, entity&)`; for example
    ///         core::jsonl_writer.
    /// @param request Selection and entity validation options.
    /// @param options Count, first index, threads and uniqueness.
    /// @param batch_seed Seed of the whole batch.
    /// @param sink Receives the entities.
    template <typename Sink>
    void for_each_entity(const entity_request& request, const core::batch_options& options,
                         std::uint64_t batch_seed, Sink&& sink) const
    {
        const auto refs = resolve_components(request);
        core::for_each_batch(options, batch_seed,
                             [&](std::uint64_t item_seed) { return generate_seeded(refs, item_seed, request); },
                             std::forward<Sink>(sink));
    }
 
    /// @brief Stream a batch of entities with a batch seed drawn from the
    ///        generator's engine.
    /// @tparam Sink Callable taking `(std::uint64_t, entity&)`.
    /// @param request Selection and entity validation options.
    /// @param options Count, first index, threads and uniqueness.
    /// @param sink Receives the entities.
    template <typename Sink>
    void for_each_entity(const entity_request& request, const core::batch_options& options,
                         Sink&& sink)
    {
        for_each_entity(request, options, _engine(), std::forward<Sink>(sink));
    }
 
    /// @}
    /// @name Concurrent Batch Generation
    /// @{
 
    /// @brief Generate multiple entities concurrently.
    ///
    /// Same entities as generate_batch(request) would give from the same engine
    /// state; each entity is generated in its own async task. Results are
    /// returned in order. Components, observers and the request's validator
    /// (including captured state) must be thread-safe. In a WebAssembly build without threads
    /// (Emscripten without `-pthread`) the tasks run one after another, with
    /// the same results.
    /// @param request Selection, batch count and entity validation options.
    /// @return A vector of generated entities.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] std::vector<entity> generate_batch_async(const entity_request& request)
    {
        const auto refs = resolve_components(request);
        return generate_batch_async_seeded(refs, request, _engine());
    }
 
    /// @brief Generate multiple entities concurrently using a seed.
    ///
    /// Gives the same entities as generate_batch(request, call_seed).
    /// @param request Selection, batch count and entity validation options.
    /// @param call_seed Seed for reproducible results.
    /// @return A vector of generated entities.
    /// @throws std::invalid_argument If both selection fields are set.
    /// @throws std::out_of_range If the requested group does not exist.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] std::vector<entity> generate_batch_async(
        const entity_request& request, std::uint64_t call_seed) const
    {
        return generate_batch_async_seeded(resolve_components(request), request, call_seed);
    }
 
    /// @}
    /// @name Component Groups
    /// @{
 
    /// @brief Register a named group of component keys.
    /// @param group_name Name for the group.
    /// @param component_keys Keys in the group.
    /// @return `*this` for chaining.
    eg& add_group(const std::wstring& group_name,
                  std::vector<std::wstring> component_keys)
    {
        _groups[group_name] = std::move(component_keys);
        return *this;
    }
 
    /// @brief Remove a named group.
    /// @param group_name The group to remove.
    /// @return `*this` for chaining.
    eg& remove_group(const std::wstring& group_name)
    {
        _groups.erase(group_name);
        return *this;
    }
 
    /// @brief Check if a named group exists.
    /// @param group_name The group name to look up.
    /// @return `true` if the group exists.
    [[nodiscard]] bool has_group(const std::wstring& group_name) const
    {
        return _groups.contains(group_name);
    }
 
    /// @brief Generate an entity using a named group.
    /// @param request Options with a registered group name.
    /// @return The generated entity.
    /// @throws std::out_of_range If the group does not exist.
    /// @throws std::invalid_argument If the group is absent or component_keys is set.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] entity generate_group(const entity_request& request)
    {
        require_group(request);
        return generate(request);
    }
 
    /// @brief Generate an entity using a named group with a seed.
    /// @param request Options with a registered group name.
    /// @param call_seed Seed for reproducible results.
    /// @return The generated entity.
    /// @throws std::out_of_range If the group does not exist.
    /// @throws std::invalid_argument If the group is absent or component_keys is set.
    /// @throws std::runtime_error If component or entity validation is exhausted.
    [[nodiscard]] entity generate_group(const entity_request& request,
                                        std::uint64_t call_seed) const
    {
        require_group(request);
        return generate(request, call_seed);
    }
 
    /// @}
 
  private:
    // Component entry: key + owned component pointer.
    struct component_entry
    {
        std::wstring key;
        std::unique_ptr<component> comp;
    };
 
    // Reference to a component entry for filtered generation.
    struct component_ref
    {
        std::wstring key;
        std::reference_wrapper<const component> comp;
        double effective_weight;
        std::vector<std::wstring> depends;
    };
 
    // Type alias for the observer list.
    using observer_list =
        std::vector<std::shared_ptr<generation_observer>>;
 
    // Notify all observers in a list by calling a member function. The
    // arguments go to every observer, so they are passed as lvalues (never
    // forwarded: the first observer could move from them).
    template <typename Hook, typename... Args>
    static void notify_all(const observer_list& observers,
                           Hook hook, const Args&... args)
    {
        for (const auto& obs : observers)
        {
            ((*obs).*hook)(args...);
        }
    }
 
    // Convenience: notify using the instance's observer list.
    template <typename Hook, typename... Args>
    void notify(Hook hook, const Args&... args) const
    {
        notify_all(_observers, hook, args...);
    }
 
    // Emscripten without pthreads cannot start threads; deferred tasks give
    // the same entities, generated on the calling thread.
#if defined(__EMSCRIPTEN__) && !defined(__EMSCRIPTEN_PTHREADS__)
    static constexpr std::launch async_policy = std::launch::deferred;
#else
    static constexpr std::launch async_policy = std::launch::async;
#endif
 
    // The call seeds of a batch: item i is core::item_seed(call_seed, i).
    [[nodiscard]] static std::vector<std::uint64_t> batch_seeds(
        std::size_t count, std::uint64_t call_seed) // NOLINT(bugprone-easily-swappable-parameters)
    {
        std::vector<std::uint64_t> seeds(count);
        for (std::size_t i = 0; i < count; ++i)
        {
            seeds[i] = core::item_seed(call_seed, i);
        }
        return seeds;
    }
 
    // One entity from a call seed: hooks, entity validation and retries.
    // Attempt 0 uses the call seed itself; attempt k uses the k-th value of
    // core::rng{call_seed}.split("attempt").
    [[nodiscard]] entity generate_seeded(std::span<const component_ref> refs,
                                         std::uint64_t call_seed,
                                         const entity_request& request) const
    {
        const auto& validator = request.validator;
        notify_all(_observers, &generation_observer::on_before_generate);
        auto attempts = core::rng{call_seed}.split("attempt");
        std::optional<entity> accepted;
        for (std::size_t attempt = 0; attempt <= _max_retries; ++attempt)
        {
            if (attempt > 0)
                notify_all(_observers,
                    &generation_observer::on_before_entity_retry, attempt);
            const std::uint64_t entity_seed = attempt == 0 ? call_seed : attempts();
            auto e = generate_impl(refs, entity_seed, _max_retries, _observers, request.inputs);
            if (attempt > 0)
                notify_all(_observers,
                    &generation_observer::on_after_entity_retry, attempt);
            if (!validator || validator(e))
            {
                accepted = std::move(e);
                break;
            }
        }
 
        if (!accepted)
        {
            notify_all(_observers, &generation_observer::on_entity_fail);
            throw std::runtime_error(
                "entity validation failed after max retries");
        }
        notify_all(_observers, &generation_observer::on_after_generate, *accepted);
        return std::move(*accepted);
    }
 
    // One generation attempt. Component k draws from
    // core::rng{entity_seed}.split(to_utf8(k)): its weight roll from
    // .split("weight"), its seeds (first try, then retries) from
    // .split("seed"); the component's own engine is core::rng{its seed}.
    [[nodiscard]] static entity generate_impl(
        std::span<const component_ref> components, std::uint64_t entity_seed, // NOLINT(bugprone-easily-swappable-parameters)
        std::size_t max_retries, const observer_list& observers, const input_map& inputs)
    {
        entity generated_entity;
        generation_context ctx;
        ctx._inputs = &inputs;
        generated_entity._seed = entity_seed;
        generated_entity._entries.reserve(components.size());
        ctx._values.reserve(components.size());
        const core::rng root{entity_seed};
 
        for (const auto& ref : components)
        {
            const auto stream = root.split(core::to_utf8(ref.key));
 
            // A component whose dependency did not run does not run either.
            if (!std::ranges::all_of(ref.depends, [&ctx](const auto& dep) { return ctx.has(dep); }))
            {
                notify_all(observers,
                    &generation_observer::on_skip, ref.key);
                continue;
            }
 
            // Roll against the effective weight.
            if (ref.effective_weight < 1.0)
            {
                auto roll = stream.split("weight");
                if (core::uniform01(roll) >= ref.effective_weight)
                {
                    notify_all(observers,
                        &generation_observer::on_skip, ref.key);
                    continue;
                }
            }
 
            // Conditional check: skip if the component opts out based on context.
            if (!ref.comp.get().should_generate(ctx))
            {
                notify_all(observers,
                    &generation_observer::on_skip, ref.key);
                continue;
            }
 
            notify_all(observers,
                &generation_observer::on_before_component, ref.key);
 
            auto seeds = stream.split("seed");
            auto component_seed = seeds();
            ctx._random = core::rng{component_seed};
            auto value = ref.comp.get().generate(ctx);
 
            // Component-level validation with retries.
            for (std::size_t retry = 0;
                 retry < max_retries && !ref.comp.get().validate(value);
                 ++retry)
            {
                notify_all(observers,
                    &generation_observer::on_before_retry, ref.key, retry + 1);
                component_seed = seeds();
                ctx._random = core::rng{component_seed};
                value = ref.comp.get().generate(ctx);
                notify_all(observers,
                    &generation_observer::on_after_retry, ref.key,
                    retry + 1, value);
            }
 
            if (!ref.comp.get().validate(value))
            {
                notify_all(observers,
                    &generation_observer::on_component_fail, ref.key);
                throw std::runtime_error(
                    "component validation failed after max retries");
            }
 
            auto display = ref.comp.get().to_string(value);
            auto json = ref.comp.get().to_json(value);
 
            notify_all(observers,
                &generation_observer::on_after_component, ref.key, value);
 
            const auto& added = generated_entity._entries.emplace_back(
                entity::entry{.key = ref.key, .label = ref.comp.get().label(),
                              .value = std::move(value),
                              .display = std::move(display),
                              .seed = component_seed, .json = std::move(json)});
            ctx._values.emplace_back(&added.key, &added.value);
        }
 
        generated_entity._data = replay_data(components, ctx, inputs);
        return generated_entity;
    }
 
    // --- Component resolution ---------------------------------------------
 
    static void require_group(const entity_request& request)
    {
        if (!request.group)
            throw std::invalid_argument("generate_group requires a group");
    }
 
    [[nodiscard]] std::vector<component_ref> resolve_components(
        const entity_request& request) const
    {
        if (request.group && request.component_keys)
            throw std::invalid_argument("group and component_keys are mutually exclusive");
        if (request.group)
        {
            const auto it = _groups.find(*request.group);
            if (it == _groups.end())
                throw std::out_of_range("group not found");
            return with_dependencies(filter_components(it->second));
        }
        return with_dependencies(request.component_keys ? filter_components(*request.component_keys)
                                                        : all_component_refs());
    }
 
    [[nodiscard]] std::vector<entity> generate_batch_seeded(
        std::span<const component_ref> refs, const entity_request& request,
        std::uint64_t call_seed) const
    {
        std::vector<entity> entities;
        entities.reserve(request.count);
        for (const auto entity_seed : batch_seeds(request.count, call_seed))
            entities.push_back(generate_seeded(refs, entity_seed, request));
        return entities;
    }
 
    [[nodiscard]] std::vector<entity> generate_batch_async_seeded(
        std::span<const component_ref> refs, const entity_request& request,
        std::uint64_t call_seed) const
    {
        std::vector<std::future<entity>> futures;
        futures.reserve(request.count);
        for (const auto entity_seed : batch_seeds(request.count, call_seed))
        {
            futures.push_back(std::async(async_policy, [this, refs, &request, entity_seed] {
                return generate_seeded(refs, entity_seed, request);
            }));
        }
 
        std::vector<entity> entities;
        entities.reserve(request.count);
        std::ranges::transform(futures, std::back_inserter(entities),
            [](auto& f) { return f.get(); });
        return entities;
    }
 
    // Build a component_ref span from the owned component entries.
    [[nodiscard]] std::vector<component_ref> all_component_refs() const
    {
        std::vector<component_ref> refs;
        refs.reserve(_components.size());
        std::ranges::transform(_components, std::back_inserter(refs),
            [this](const auto& entry) -> component_ref {
                return make_ref(entry);
            });
        return refs;
    }
 
    // Filter registered components by the requested keys, preserving
    // registration order.
    [[nodiscard]] std::vector<component_ref> filter_components(
        std::span<const std::wstring> component_keys) const
    {
        std::vector<component_ref> filtered;
 
        auto matching = _components
            | std::views::filter([&](const auto& entry) {
                return std::ranges::contains(component_keys, entry.key);
            })
            | std::views::transform([this](const auto& entry) -> component_ref {
                return make_ref(entry);
            });
        std::ranges::copy(matching, std::back_inserter(filtered));
 
        return filtered;
    }
 
    [[nodiscard]] component_ref make_ref(const component_entry& entry) const
    {
        return {entry.key, std::cref(*entry.comp), effective_weight(entry.key, *entry.comp),
                entry.comp->depends_on()};
    }
 
    // Adds the dependencies of the selected components (transitively) and
    // orders the set so every component comes after its dependencies, keeping
    // registration order otherwise. A set without dependencies is returned
    // as it is.
    [[nodiscard]] std::vector<component_ref> with_dependencies(std::vector<component_ref> selected) const
    {
        if (std::ranges::all_of(selected, [](const auto& r) { return r.depends.empty(); }))
            return selected;
 
        std::set<std::wstring> wanted;
        std::vector<std::wstring> pending;
        for (const auto& r : selected)
        {
            if (wanted.insert(r.key).second) pending.push_back(r.key);
        }
        for (std::size_t i = 0; i < pending.size(); ++i)
        {
            const auto it = std::ranges::find(_components, pending[i], &component_entry::key);
            for (const auto& dep : it->comp->depends_on())
            {
                if (!has(dep))
                    throw std::invalid_argument("component '" + core::to_utf8(pending[i]) +
                                                "' depends on '" + core::to_utf8(dep) +
                                                "', which is not registered");
                if (wanted.insert(dep).second) pending.push_back(dep);
            }
        }
 
        std::vector<component_ref> remaining;
        for (const auto& entry : _components)
        {
            if (wanted.contains(entry.key)) remaining.push_back(make_ref(entry));
        }
        std::vector<component_ref> ordered;
        std::set<std::wstring> emitted;
        while (!remaining.empty())
        {
            const auto next = std::ranges::find_if(remaining, [&emitted](const auto& r) {
                return std::ranges::all_of(r.depends, [&emitted](const auto& d) { return emitted.contains(d); });
            });
            if (next == remaining.end())
            {
                std::string names;
                for (const auto& r : remaining) names += (names.empty() ? "'" : ", '") + core::to_utf8(r.key) + "'";
                throw std::logic_error("components depend on each other in a cycle: " + names);
            }
            emitted.insert(next->key);
            ordered.push_back(std::move(*next));
            remaining.erase(next);
        }
        return ordered;
    }
 
    // Hash of the request's inputs and of the data of the components that ran.
    // Nothing to hash gives 0.
    [[nodiscard]] static std::uint64_t replay_data(std::span<const component_ref> components,
                                                   const generation_context& ctx,
                                                   const input_map& inputs)
    {
        std::string bytes;
        const auto put_u64 = [&bytes](std::uint64_t n) {
            for (int shift = 0; shift < 64; shift += 8) bytes.push_back(static_cast<char>((n >> shift) & 0xFFU));
        };
        for (const auto& [name, value] : inputs)
        {
            bytes += 'i';
            put_u64(name.size());
            bytes += name;
            bytes += static_cast<char>(value.index());
            std::visit(
                [&](const auto& v) {
                    using V = std::decay_t<decltype(v)>;
                    if constexpr (std::is_same_v<V, bool>) bytes += v ? '\1' : '\0';
                    else if constexpr (std::is_same_v<V, std::int64_t>) put_u64(static_cast<std::uint64_t>(v));
                    else if constexpr (std::is_same_v<V, double>) put_u64(std::bit_cast<std::uint64_t>(v));
                    else
                    {
                        put_u64(v.size());
                        bytes += v;
                    }
                },
                value);
        }
        for (const auto& ref : components)
        {
            const auto hash = ref.comp.get().data_hash();
            if (hash == 0 || !ctx.has(ref.key)) continue;
            const auto key = core::to_utf8(ref.key);
            bytes += 'c';
            put_u64(key.size());
            bytes += key;
            put_u64(hash);
        }
        return bytes.empty() ? 0 : core::fnv1a64(bytes);
    }
 
    // Rejects keys the JSON could not hold: empty path segments, or a key
    // that is also the parent of another.
    // Build every component of a recipe, then add them, so a bad row adds none.
    eg& add_recipe_(const core::tsv_document& doc)
    {
        std::vector<std::unique_ptr<component>> built;
        std::set<std::string> seen;
        for (const auto& row : doc.rows())
        {
            const auto key = row.get<std::string>("key");
            if (!seen.insert(key).second) throw row.error("key", "key repeated in the recipe");
            built.push_back(recipe_component_(row, key));
        }
        for (const auto& comp : built) check_key(comp->key());
        for (auto& comp : built) add(std::move(comp));
        return *this;
    }
 
    static std::unique_ptr<component> recipe_component_(const core::tsv_row& row, const std::string& key)
    {
        const auto kind = row.get<std::string>("kind");
        const auto values = row.get<std::string>("values");
        const auto hash = core::fnv1a64(key + '\t' + kind + '\t' + values);
 
        if (kind == "constant")
        {
            return finish_recipe_(field(core::from_utf8(key),
                                        [text = core::from_utf8(values)](const generation_context&) { return text; }),
                                  row, key, hash);
        }
        if (kind == "choice")
        {
            std::vector<std::wstring> choices;
            for (const auto item : row.list("values", '|')) choices.push_back(core::from_utf8(item));
            return finish_recipe_(field(core::from_utf8(key),
                                        [choices](const generation_context& ctx)
                                        { return core::pick(ctx.random(), choices); }),
                                  row, key, hash);
        }
        if (kind == "weighted")
        {
            std::vector<std::wstring> choices;
            std::vector<double> weights;
            for (const auto item : row.list("values", '|'))
            {
                const auto colon = item.rfind(':');
                if (colon == std::string_view::npos)
                    throw row.error("values", "expected value:weight, got '" + std::string{item} + "'");
                const auto weight = core::detail::parse_number<double>(item.substr(colon + 1));
                if (!weight || !(*weight >= 0.0))
                    throw row.error("values", "weight must be a number of 0 or more in '" + std::string{item} + "'");
                choices.push_back(core::from_utf8(item.substr(0, colon)));
                weights.push_back(*weight);
            }
            if (!std::ranges::any_of(weights, [](double w) { return w > 0.0; }))
                throw row.error("values", "at least one weight must be positive");
            return finish_recipe_(field(core::from_utf8(key),
                                        [choices, dist = core::discrete{weights}](const generation_context& ctx)
                                        { return choices[dist(ctx.random())]; }),
                                  row, key, hash);
        }
        if (kind == "int" || kind == "real")
        {
            const std::string_view range = values;
            const auto dots = range.find("..");
            if (dots == std::string_view::npos)
                throw row.error("values", "expected lo..hi, got '" + values + "'");
            if (kind == "int")
            {
                const auto lo = core::detail::parse_number<std::int64_t>(range.substr(0, dots));
                const auto hi = core::detail::parse_number<std::int64_t>(range.substr(dots + 2));
                if (!lo || !hi || *lo > *hi)
                    throw row.error("values", "expected whole numbers lo..hi with lo <= hi, got '" + values + "'");
                return finish_recipe_(field(core::from_utf8(key),
                                            [lo = *lo, hi = *hi](const generation_context& ctx)
                                            { return core::uniform_int(ctx.random(), lo, hi); }),
                                      row, key, hash);
            }
            const auto lo = core::detail::parse_number<double>(range.substr(0, dots));
            const auto hi = core::detail::parse_number<double>(range.substr(dots + 2));
            if (!lo || !hi || !(*lo <= *hi))
                throw row.error("values", "expected finite numbers lo..hi with lo <= hi, got '" + values + "'");
            return finish_recipe_(field(core::from_utf8(key),
                                        [lo = *lo, hi = *hi](const generation_context& ctx)
                                        {
                                            const double v = core::uniform_real(ctx.random(), lo, hi);
                                            return v >= hi && hi > lo ? std::nextafter(hi, lo) : v;
                                        }),
                                  row, key, hash);
        }
        throw row.error("kind", "expected constant, choice, weighted, int or real, got '" + kind + "'");
    }
 
    // Apply the columns every kind shares and wrap the field as a component.
    template <typename T>
    static std::unique_ptr<component> finish_recipe_(field_component<T> f, const core::tsv_row& row,
                                                     const std::string& key, std::uint64_t hash)
    {
        const auto label = row.get_or<std::string>("label", key);
        std::vector<std::wstring> depends;
        if (row.has("depends_on"))
        {
            for (const auto item : row.list("depends_on")) depends.push_back(core::from_utf8(item));
        }
        const auto weight = row.get_or<double>("weight", 1.0);
        if (!(weight >= 0.0 && weight <= 1.0)) throw row.error("weight", "must be between 0 and 1");
        return std::make_unique<field_component<T>>(std::move(f)
                                                        .label(core::from_utf8(label))
                                                        .depends_on(std::move(depends))
                                                        .weight(weight)
                                                        .data_hash(hash));
    }
 
    void check_key(const std::wstring& key) const
    {
        const auto path = core::to_utf8(key);
        const auto bad = [&path](const std::string& why) {
            return std::invalid_argument("component key '" + path + "' " + why);
        };
        if (!path.empty() && (path.front() == '.' || path.back() == '.' || path.find("..") != std::string::npos))
            throw bad("has an empty path segment");
        for (const auto& other : _components)
        {
            if (other.key == key) continue;
            const auto o = core::to_utf8(other.key);
            if (o.starts_with(path + ".") || path.starts_with(o + "."))
                throw bad("collides with '" + o + "' (one is the parent of the other)");
        }
    }
 
    // Resolve the effective weight for a component: override wins, then
    // the component's own weight() method.
    [[nodiscard]] double effective_weight(
        const std::wstring& key, const component& comp) const
    {
        auto it = _weight_overrides.find(key);
        return it != _weight_overrides.end() ? it->second : comp.weight();
    }
 
    // Registered components in insertion order.
    std::vector<component_entry> _components;
 
    // Named groups of component keys.
    std::map<std::wstring, std::vector<std::wstring>> _groups;
 
    // Per-component weight overrides (key -> weight).
    std::map<std::wstring, double> _weight_overrides;
 
    // Generation lifecycle observers (optional).
    observer_list _observers;
 
    // Maximum retries for component and entity validation.
    std::size_t _max_retries{10};
 
    // Internal random engine for the generator.
    core::rng _engine{core::rng::from_entropy()};
};
} // namespace dasmig
 
#endif // DASMIG_ENTITYGEN_HPP