Generation Context Design

/// @brief Scoped key-value store for generation parameters.
///
/// Models a lexically-scoped environment where lookups walk up a
/// chain of parent environments. Used to pass contextual data
/// (e.g. tenant_id, modified_by, parent entity IDs) through a
/// generation graph without coupling generators to each other.
///
/// Child environments inherit all parent bindings and can shadow
/// them with local overrides. This enables natural scoping: when
/// generating a party and its child identifiers, the party_id
/// binding is visible to identifier generators but not to unrelated
/// generators.
///
/// Environments are immutable after construction. To add bindings,
/// create a child environment with the new entries.
class generation_environment final {
public:
    using entries = std::unordered_map<std::string, std::string>;

    /// @brief Construct a root environment with initial bindings.
    /// @param initial Key-value pairs for this scope.
    explicit generation_environment(entries initial = {});

    /// @brief Construct a child environment that inherits from parent.
    /// @param parent The parent environment. Must outlive this child
    ///   (enforced by shared_ptr).
    /// @param overrides Key-value pairs for this scope. Shadow any
    ///   parent bindings with the same key.
    generation_environment(
        std::shared_ptr<const generation_environment> parent,
        entries overrides);

    /// @brief Look up a value by key.
    ///
    /// Searches this scope first, then walks up the parent chain.
    /// @return The value if found in any scope, or std::nullopt.
    std::optional<std::string> get(const std::string& key) const;

    /// @brief Look up a value with a default.
    /// @return The value if found, or default_value.
    std::string get_or(const std::string& key,
                       const std::string& default_value) const;

    /// @brief Check whether a key exists in any scope.
    bool has(const std::string& key) const;

    /// @brief Access the parent environment, if any.
    std::shared_ptr<const generation_environment> parent() const;

private:
    std::shared_ptr<const generation_environment> parent_;
    entries entries_;
};

/// @brief Provides randomness and reproducible value generation.
///
/// Encapsulates all sources of randomness used during synthetic data
/// generation: seeded RNG, UUID generation, timestamp generation,
/// and random selection from collections. A single engine instance
/// is shared across an entire generation run to ensure
/// reproducibility from a given seed.
class generation_engine final {
public:
    /// @brief Construct with explicit seed for reproducibility.
    explicit generation_engine(std::uint64_t seed);

    /// @brief Construct with random seed.
    generation_engine();

    /// @brief The seed used for this engine.
    std::uint64_t seed() const;

    /// @brief Generate a random integer in [min, max].
    int random_int(int min, int max);

    /// @brief Generate a random boolean with given probability.
    bool random_bool(double probability = 0.5);

    /// @brief Pick a random element from a vector.
    template<typename T>
    const T& pick(const std::vector<T>& items);

    /// @brief Pick a random element from an array.
    template<typename T, std::size_t N>
    const T& pick(const std::array<T, N>& items);

    /// @brief Generate a v7 UUID using the shared RNG.
    boost::uuids::uuid generate_uuid();

    /// @brief Generate a timestamp in the past.
    std::chrono::system_clock::time_point
    past_timepoint(int years_back = 3);

    /// @brief Generate a random alphanumeric string.
    std::string alphanumeric(std::size_t length);

private:
    std::uint64_t seed_;
    std::mt19937_64 engine_;
};

/// @brief Top-level container for synthetic data generation.
///
/// Combines a shared generation engine (randomness) with a scoped
/// generation environment (contextual data). Generators receive
/// this type and use it for both random value generation and
/// looking up contextual bindings like modified_by or parent
/// entity IDs.
///
/// Child contexts share the same engine (preserving RNG sequence)
/// but introduce a new environment scope with additional bindings.
/// This enables natural scoping when generating entity graphs:
///
/// @code
/// auto ctx = make_generation_context(h);
/// auto party = generate_synthetic_party(ctx);
/// auto child_ctx = ctx.child({{"party_id", to_string(party.id)}});
/// auto id = generate_synthetic_party_identifier(child_ctx);
/// @endcode
class generation_context final {
public:
    using entries = generation_environment::entries;

    /// @brief Create a root context with seed and initial bindings.
    explicit generation_context(std::uint64_t seed,
                                entries initial = {});

    /// @brief Create a root context with random seed.
    explicit generation_context(entries initial = {});

    /// @brief Create a child context with additional bindings.
    ///
    /// Shares the same engine (preserving RNG sequence). Creates a
    /// new environment scope that inherits from this context's
    /// environment.
    generation_context child(entries overrides) const;

    /// @brief Access the generation engine (randomness).
    generation_engine& engine();
    const generation_engine& engine() const;

    /// @brief Access the generation environment (scoped data).
    const generation_environment& env() const;

    // Convenience delegations to engine.
    int random_int(int min, int max);
    bool random_bool(double probability = 0.5);
    boost::uuids::uuid generate_uuid();
    std::chrono::system_clock::time_point
    past_timepoint(int years_back = 3);
    std::string alphanumeric(std::size_t length);

    template<typename T>
    const T& pick(const std::vector<T>& items);

    template<typename T, std::size_t N>
    const T& pick(const std::array<T, N>& items);

private:
    /// @brief Private constructor for child contexts.
    generation_context(
        std::shared_ptr<generation_engine> engine,
        std::shared_ptr<const generation_environment> env);

    std::shared_ptr<generation_engine> engine_;
    std::shared_ptr<const generation_environment> env_;
};

/// @brief Well-known keys for the generation environment.
///
/// Constants for commonly-used environment bindings. Generators
/// should use these rather than string literals to avoid typos
/// and enable tooling support (find-references, rename, etc.).
namespace generation_keys {

/// The username to use for modified_by audit trail fields.
/// Typically set to the database session user in test contexts,
/// or the logged-in user in application contexts.
inline constexpr std::string_view modified_by = "modified_by";

/// The tenant ID for the current generation scope.
inline constexpr std::string_view tenant_id = "tenant_id";

/// Parent entity IDs, set when generating child entities.
inline constexpr std::string_view party_id = "party_id";
inline constexpr std::string_view counterparty_id = "counterparty_id";
inline constexpr std::string_view account_id = "account_id";
inline constexpr std::string_view catalog_id = "catalog_id";

}

// database_helper.hpp
/// @brief Returns the database session user for the test connection.
///
/// Queries SELECT current_user from the database. Used to populate
/// the generation environment's modified_by key, ensuring generated
/// data passes trigger-based audit trail validation.
std::string db_user() const;

// scoped_database_helper.hpp
std::string db_user() const { return helper_.db_user(); }

// database_helper.cpp
std::string database_helper::db_user() const {
    return execute_raw_string_query(ctx_, "SELECT current_user");
}

/// @brief Create a generation context pre-populated from test helpers.
generation_context make_generation_context(
    const scoped_database_helper& h);

generation_context make_generation_context(
    const scoped_database_helper& h, std::uint64_t seed);

// Before: multiple overloads
account generate_synthetic_account();
account generate_synthetic_account(const tenant_id& tid);
account generate_synthetic_account(generation_context& ctx);

// After: single signature
account generate_synthetic_account(generation_context& ctx);

// Batch variant
std::vector<account> generate_synthetic_accounts(
    std::size_t n, generation_context& ctx);

account generate_synthetic_account(generation_context& ctx) {
    const auto tid = ctx.env().get_or(
        std::string(generation_keys::tenant_id), "");
    const auto modified_by = ctx.env().get_or(
        std::string(generation_keys::modified_by), "system");

    return account{
        .id = ctx.generate_uuid(),
        .modified_by = modified_by,
        .tenant_id = tid,
        .username = faker::internet::username(),
        // ...
    };
}

auto ctx = generation_context(options.seed.value_or(...), {
    {std::string(generation_keys::modified_by), "system"}
});

// Phase 1: base entities
for (auto i = 0u; i < options.account_count; ++i)
    result.accounts.push_back(generate_synthetic_account(ctx));

// Phase 2: entities with children
for (auto i = 0u; i < options.party_count; ++i) {
    auto party = generate_synthetic_party(ctx);
    result.parties.push_back(party);

    auto party_ctx = ctx.child({
        {std::string(generation_keys::party_id),
         to_string(party.id)}
    });
    for (auto j = 0u; j < ids_per_party; ++j)
        result.identifiers.push_back(
            generate_synthetic_party_identifier(party_ctx));
}