version Enum

namespace keychain {
    enum class version {
        // Major versions
        VERSION_1_0,    // Legacy version 1.0
        VERSION_2_0,    // Version 2.0
        VERSION_2_1,    // Version 2.1
        VERSION_2_2,    // Version 2.2
        VERSION_2_3,    // Version 2.3
        VERSION_2_4,    // Version 2.4 (latest 2.x)
        VERSION_3_0,    // Version 3.0 (current)

        // Special values
        UNKNOWN,        // Unknown or unsupported version
        CURRENT         // Current library version (alias for latest)
    };
}

#include <keychain/keychain.h>

// Get current library version
keychain::version current_version = keychain::version::CURRENT;
std::cout << "Running Keychain Core " << to_string(current_version) << std::endl;

// Check version compatibility
bool is_compatible(keychain::version required_version) {
    keychain::version current = keychain::version::CURRENT;

    // 3.0 is compatible with all 3.x versions
    if (current >= keychain::version::VERSION_3_0 &&
        required_version >= keychain::version::VERSION_3_0) {
        return true;
    }

    // 2.x versions have limited compatibility
    if (current >= keychain::version::VERSION_2_0 &&
        current < keychain::version::VERSION_3_0 &&
        required_version >= keychain::version::VERSION_2_0 &&
        required_version < keychain::version::VERSION_3_0) {
        return true;
    }

    return false;
}

// Feature detection by version
bool supports_composable_crypto(keychain::version ver) {
    return ver >= keychain::version::VERSION_3_0;
}

bool supports_dids(keychain::version ver) {
    return ver >= keychain::version::VERSION_3_0;
}

bool supports_verifiable_credentials(keychain::version ver) {
    return ver >= keychain::version::VERSION_3_0;
}

// Version comparison operators
bool compare_versions() {
    keychain::version v2_4 = keychain::version::VERSION_2_4;
    keychain::version v3_0 = keychain::version::VERSION_3_0;
    keychain::version current = keychain::version::CURRENT;

    // Comparison operations
    assert(v3_0 > v2_4);           // 3.0 is newer than 2.4
    assert(v2_4 < v3_0);           // 2.4 is older than 3.0
    assert(current >= v3_0);       // Current is at least 3.0

    // Version ordering
    std::vector<keychain::version> versions = {
        keychain::version::VERSION_2_4,
        keychain::version::VERSION_3_0,
        keychain::version::VERSION_2_1,
        keychain::version::CURRENT
    };

    std::sort(versions.begin(), versions.end());
    // Result: VERSION_2_1, VERSION_2_4, VERSION_3_0, CURRENT

    return true;
}

// Version-aware data migration
class version_migration {
public:
    static keychain::serialized_data migrate_data(
        const keychain::serialized_data& data,
        keychain::version from_version,
        keychain::version to_version) {

        if (from_version == to_version) {
            return data; // No migration needed
        }

        keychain::serialized_data migrated = data;

        // Migrate from 2.x to 3.0
        if (from_version < keychain::version::VERSION_3_0 &&
            to_version >= keychain::version::VERSION_3_0) {
            migrated = migrate_2x_to_3x(migrated);
        }

        return migrated;
    }

private:
    static keychain::serialized_data migrate_2x_to_3x(
        const keychain::serialized_data& v2_data) {

        // Convert URI to DID format
        auto data_obj = v2_data.get_object();

        if (data_obj.count("uri") > 0) {
            std::string old_uri = data_obj["uri"].get_string();
            std::string new_did = convert_uri_to_did(old_uri);
            data_obj["did"] = keychain::serialized_data(new_did);
            data_obj.erase("uri");
        }

        // Update signature format
        if (data_obj.count("signature") > 0) {
            auto old_sig = data_obj["signature"].get_string();
            auto new_attestation = convert_signature_to_attestation(old_sig);
            data_obj["attestations"] = new_attestation;
            data_obj.erase("signature");
        }

        keychain::serialized_data migrated;
        migrated.set_object(data_obj);
        return migrated;
    }
};

// Feature availability checking
class feature_detector {
public:
    static bool has_feature(const std::string& feature_name,
                           keychain::version version = keychain::version::CURRENT) {
        static const std::map<std::string, keychain::version> feature_versions = {
            {"basic_pki", keychain::version::VERSION_1_0},
            {"enhanced_pki", keychain::version::VERSION_2_0},
            {"consensus", keychain::version::VERSION_2_1},
            {"composable_crypto", keychain::version::VERSION_3_0},
            {"dids", keychain::version::VERSION_3_0},
            {"verifiable_credentials", keychain::version::VERSION_3_0},
            {"multi_signature", keychain::version::VERSION_3_0},
            {"transactions", keychain::version::VERSION_3_0}
        };

        auto it = feature_versions.find(feature_name);
        if (it == feature_versions.end()) {
            return false; // Unknown feature
        }

        return version >= it->second;
    }

    static std::vector<std::string> get_available_features(
        keychain::version version = keychain::version::CURRENT) {

        std::vector<std::string> available;

        std::vector<std::string> all_features = {
            "basic_pki", "enhanced_pki", "consensus",
            "composable_crypto", "dids", "verifiable_credentials",
            "multi_signature", "transactions"
        };

        for (const auto& feature : all_features) {
            if (has_feature(feature, version)) {
                available.push_back(feature);
            }
        }

        return available;
    }
};

// Runtime version information
namespace version_info {

    keychain::version get_library_version() {
        return keychain::version::CURRENT;
    }

    std::string get_version_string() {
        return "3.0.0"; // Actual version string
    }

    std::string get_build_info() {
        return "Keychain Core 3.0.0 (built " __DATE__ " " __TIME__ ")";
    }

    bool is_compatible_with(keychain::version required_version) {
        keychain::version current = get_library_version();

        // Major version compatibility
        int current_major = static_cast<int>(current) / 10;
        int required_major = static_cast<int>(required_version) / 10;

        return current_major == required_major && current >= required_version;
    }

    std::vector<keychain::version> get_supported_versions() {
        return {
            keychain::version::VERSION_3_0,
            keychain::version::CURRENT
        };
    }

    void print_version_info() {
        std::cout << "Keychain Core Version Information:" << std::endl;
        std::cout << "  Version: " << get_version_string() << std::endl;
        std::cout << "  Build: " << get_build_info() << std::endl;
        std::cout << "  Features: ";

        auto features = feature_detector::get_available_features();
        for (size_t i = 0; i < features.size(); ++i) {
            std::cout << features[i];
            if (i < features.size() - 1) std::cout << ", ";
        }
        std::cout << std::endl;
    }
}

// Version-aware serialization
class versioned_serializer {
public:
    static std::string serialize_with_version(
        const keychain::serializable& object,
        keychain::version target_version = keychain::version::CURRENT) {

        // Create version header
        nlohmann::json json_data;
        json_data["format_version"] = to_string(target_version);
        json_data["created_by"] = version_info::get_version_string();
        json_data["created_at"] = get_iso8601_timestamp();

        // Serialize object data
        json_data["data"] = nlohmann::json::parse(object.to_json());

        return json_data.dump();
    }

    static std::unique_ptr<keychain::serializable> deserialize_with_version(
        const std::string& serialized_data) {

        auto json_data = nlohmann::json::parse(serialized_data);

        // Check format version
        keychain::version format_version = keychain::version::UNKNOWN;
        if (json_data.contains("format_version")) {
            format_version = from_string(json_data["format_version"]);
        }

        // Migrate if necessary
        auto data_json = json_data["data"];
        if (format_version != keychain::version::CURRENT) {
            data_json = migrate_json_format(data_json, format_version, keychain::version::CURRENT);
        }

        // Deserialize object
        return create_object_from_json(data_json.dump());
    }
};
```

== Version Negotiation

[,cpp]

== Version Summary Table

|===
|Version |Status |Key Features |Compatibility

|1.0
|End of Life
|Basic PKI
|None

|2.0-2.3
|End of Life
|Enhanced PKI, Basic Consensus
|Limited

|2.4
|Maintenance
|Stable PKI, Consensus
|2.x only

|3.0
|Current
|Composable Crypto, DIDs, VCs, Multi-sig
|3.x forward
|===

== Related Types

* xref:cpp/gateway.adoc[gateway] - Version-aware operations
* xref:cpp/serialization-format.adoc[serialization_format] - Serialization versioning
* xref:cpp/data-type.adoc[data_type] - Data type evolution

== See Also

* xref:setup/migration-3.0.adoc[Migration Guide] - Upgrading from 2.x
* {semantic-versioning}[Semantic Versioning Specification]
* {api-versioning-best-practices}[API Versioning Best Practices]