error.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright 2026 Johnson Ogundeji
#pragma once
 
#include <algorithm>
#include <cassert>
#include <stdexcept>
#include <cctype>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <fstream>
#include <limits>
#include <mutex>
#include <sstream>
#include <string>
#include <type_traits>
#include <unordered_map>
#include <utility>
#include <unordered_set>
#include <variant>
#include <vector>
 
#ifndef _WIN32
#include <fcntl.h>
#include <pwd.h>
#include <sys/stat.h>
#include <unistd.h>
#endif
 
namespace signet::forge {
 
// ---------------------------------------------------------------------------
// Error type — all signet operations return expected<T, Error>
// ---------------------------------------------------------------------------
 
enum class ErrorCode {
    OK = 0,
    IO_ERROR,
    INVALID_FILE,
    CORRUPT_FOOTER,
    CORRUPT_PAGE,
    CORRUPT_DATA,
    INVALID_ARGUMENT,
    UNSUPPORTED_ENCODING,
    UNSUPPORTED_COMPRESSION,
    UNSUPPORTED_TYPE,
    SCHEMA_MISMATCH,
    OUT_OF_RANGE,
    THRIFT_DECODE_ERROR,
    ENCRYPTION_ERROR,
    HASH_CHAIN_BROKEN,
    LICENSE_ERROR,
    LICENSE_LIMIT_EXCEEDED,
    INTERNAL_ERROR
};
 
struct Error {
    ErrorCode   code;
    std::string message;
 
    Error() : code(ErrorCode::OK) {}
    Error(ErrorCode c, std::string msg) : code(c), message(std::move(msg)) {}
 
    [[nodiscard]] bool ok() const { return code == ErrorCode::OK; }
    [[nodiscard]] explicit operator bool() const { return !ok(); }
};
 
// ---------------------------------------------------------------------------
// expected<T, Error> — lightweight result type
// ---------------------------------------------------------------------------
 
template <typename T>
class expected {
public:
    expected(const T& val) requires std::is_copy_constructible_v<T>
        : storage_(val) {}
    expected(T&& val) : storage_(std::move(val)) {}
 
    expected(const Error& err) : storage_(err) {}
    expected(Error&& err) : storage_(std::move(err)) {}
 
    expected(ErrorCode code, std::string msg)
        : storage_(Error{code, std::move(msg)}) {}
 
    [[nodiscard]] bool has_value() const { return std::holds_alternative<T>(storage_); }
    [[nodiscard]] explicit operator bool() const { return has_value(); }
 
    [[nodiscard]] const T& value() const& {
        if (!has_value()) throw std::logic_error("expected::value() called on error");
        return std::get<T>(storage_);
    }
    [[nodiscard]] T& value() & {
        if (!has_value()) throw std::logic_error("expected::value() called on error");
        return std::get<T>(storage_);
    }
    [[nodiscard]] T&& value() && {
        if (!has_value()) throw std::logic_error("expected::value() called on error");
        return std::get<T>(std::move(storage_));
    }
 
    [[nodiscard]] const Error& error() const {
        if (has_value()) throw std::logic_error("expected::error() called on value");
        return std::get<Error>(storage_);
    }
 
    [[nodiscard]] const T& operator*() const& { return value(); }
    [[nodiscard]] T& operator*() & { return value(); }
    [[nodiscard]] T&& operator*() && { return std::move(*this).value(); }
    [[nodiscard]] const T* operator->() const { return &value(); }
    [[nodiscard]] T* operator->() { return &value(); }
 
private:
    std::variant<T, Error> storage_;
};
 
template <>
class expected<void> {
public:
    expected() : err_() {}
    expected(const Error& err) : err_(err) {}
    expected(Error&& err) : err_(std::move(err)) {}
    expected(ErrorCode code, std::string msg) : err_(Error{code, std::move(msg)}) {}
 
    [[nodiscard]] bool has_value() const { return err_.ok(); }
    [[nodiscard]] explicit operator bool() const { return has_value(); }
    [[nodiscard]] const Error& error() const { return err_; }
 
private:
    Error err_;
};
 
} // namespace signet::forge
 
namespace signet::forge {
 
namespace commercial {
 
inline constexpr const char* kLicenseEnvVar = "SIGNET_COMMERCIAL_LICENSE_KEY";
inline constexpr const char* kLicenseTierEnvVar = "SIGNET_COMMERCIAL_LICENSE_TIER";
inline constexpr const char* kUsageFileEnvVar = "SIGNET_COMMERCIAL_USAGE_FILE";
inline constexpr const char* kRuntimeUserEnvVar = "SIGNET_COMMERCIAL_RUNTIME_USER";
inline constexpr const char* kRuntimeNodeEnvVar = "SIGNET_COMMERCIAL_RUNTIME_NODE";
inline constexpr uint64_t kUsagePersistIntervalRows = 10'000;
 
#if defined(SIGNET_EVAL_MAX_ROWS_MONTH_U64)
inline constexpr uint64_t kDefaultEvalMaxRowsMonth =
    static_cast<uint64_t>(SIGNET_EVAL_MAX_ROWS_MONTH_U64);
#else
inline constexpr uint64_t kDefaultEvalMaxRowsMonth = 50'000'000ull;
#endif
 
#if defined(SIGNET_EVAL_MAX_USERS_U32)
inline constexpr uint32_t kDefaultEvalMaxUsers =
    static_cast<uint32_t>(SIGNET_EVAL_MAX_USERS_U32);
#else
inline constexpr uint32_t kDefaultEvalMaxUsers = 3u;
#endif
 
#if defined(SIGNET_EVAL_MAX_NODES_U32)
inline constexpr uint32_t kDefaultEvalMaxNodes =
    static_cast<uint32_t>(SIGNET_EVAL_MAX_NODES_U32);
#else
inline constexpr uint32_t kDefaultEvalMaxNodes = 1u;
#endif
 
#if defined(SIGNET_EVAL_MAX_DAYS_U32)
inline constexpr uint32_t kDefaultEvalMaxDays =
    static_cast<uint32_t>(SIGNET_EVAL_MAX_DAYS_U32);
#else
inline constexpr uint32_t kDefaultEvalMaxDays = 30u;
#endif
 
#if defined(SIGNET_EVAL_WARN_PCT_1_U32)
inline constexpr uint32_t kDefaultEvalWarnPct1 =
    static_cast<uint32_t>(SIGNET_EVAL_WARN_PCT_1_U32);
#else
inline constexpr uint32_t kDefaultEvalWarnPct1 = 80u;
#endif
 
#if defined(SIGNET_EVAL_WARN_PCT_2_U32)
inline constexpr uint32_t kDefaultEvalWarnPct2 =
    static_cast<uint32_t>(SIGNET_EVAL_WARN_PCT_2_U32);
#else
inline constexpr uint32_t kDefaultEvalWarnPct2 = 90u;
#endif
 
struct LicensePolicy {
    bool evaluation_mode{false};
    uint64_t max_rows_month{0};
    uint32_t max_users{0};
    uint32_t max_nodes{0};
    int64_t explicit_expiry_day_utc{0};
    uint32_t max_eval_days{0};
    uint32_t warn_pct_1{kDefaultEvalWarnPct1};
    uint32_t warn_pct_2{kDefaultEvalWarnPct2};
};
 
struct UsageState {
    bool initialized{false};
    int month_tag{0};
    uint64_t rows_this_month{0};
    uint64_t last_persisted_rows_this_month{0};
    int64_t eval_start_day_utc{0};
    bool warn_pct_1_emitted{false};
    bool warn_pct_2_emitted{false};
    std::unordered_set<std::string> users;
    std::unordered_set<std::string> nodes;
};
 
[[nodiscard]] inline uint64_t fnv1a64(const char* data, size_t size) noexcept {
    constexpr uint64_t kOffset = 14695981039346656037ull;
    constexpr uint64_t kPrime  = 1099511628211ull;
 
    uint64_t hash = kOffset;
    for (size_t i = 0; i < size; ++i) {
        hash ^= static_cast<uint8_t>(data[i]);
        hash *= kPrime;
    }
    return hash;
}
 
[[nodiscard]] inline std::string trim_copy(const std::string& in) {
    size_t start = 0;
    while (start < in.size() && std::isspace(static_cast<unsigned char>(in[start]))) {
        ++start;
    }
 
    size_t end = in.size();
    while (end > start && std::isspace(static_cast<unsigned char>(in[end - 1]))) {
        --end;
    }
 
    return in.substr(start, end - start);
}
 
[[nodiscard]] inline std::string to_lower_ascii(std::string value) {
    for (char& ch : value) {
        ch = static_cast<char>(std::tolower(static_cast<unsigned char>(ch)));
    }
    return value;
}
 
[[nodiscard]] inline std::string sanitize_identity(std::string value,
                                                   const char* fallback) {
    value = trim_copy(value);
    if (value.empty()) {
        return fallback;
    }
 
    if (value.size() > 128) {
        value.resize(128);
    }
 
    for (char& c : value) {
        if (std::isalnum(static_cast<unsigned char>(c)) ||
            c == '-' || c == '_' || c == '.' || c == '@') {
            continue;
        }
        c = '_';
    }
    return value;
}
 
[[nodiscard]] inline std::unordered_map<std::string, std::string>
parse_claims(const std::string& text) {
    std::unordered_map<std::string, std::string> out;
    std::stringstream ss(text);
    std::string token;
 
    while (std::getline(ss, token, ';')) {
        auto pos = token.find('=');
        if (pos == std::string::npos || pos == 0 || pos + 1 >= token.size()) {
            continue;
        }
        std::string key = to_lower_ascii(trim_copy(token.substr(0, pos)));
        std::string val = trim_copy(token.substr(pos + 1));
        if (!key.empty() && !val.empty()) {
            out[key] = val;
        }
    }
 
    return out;
}
 
[[nodiscard]] inline bool parse_u64(const std::string& text, uint64_t& out) {
    if (text.empty()) return false;
 
    uint64_t value = 0;
    for (char ch : text) {
        if (!std::isdigit(static_cast<unsigned char>(ch))) return false;
        const uint64_t digit = static_cast<uint64_t>(ch - '0');
        if (value > ((std::numeric_limits<uint64_t>::max)() - digit) / 10ull) {
            return false;
        }
        value = (value * 10ull) + digit;
    }
 
    out = value;
    return true;
}
 
[[nodiscard]] inline bool parse_u32(const std::string& text, uint32_t& out) {
    uint64_t value = 0;
    if (!parse_u64(text, value) || value > (std::numeric_limits<uint32_t>::max)()) {
        return false;
    }
    out = static_cast<uint32_t>(value);
    return true;
}
 
[[nodiscard]] inline constexpr int64_t days_from_civil(int y, unsigned m,
                                                       unsigned d) noexcept {
    y -= m <= 2;
    const int era = (y >= 0 ? y : y - 399) / 400;
    const unsigned yoe = static_cast<unsigned>(y - era * 400);
    const unsigned mp = (m > 2u) ? (m - 3u) : (m + 9u);
    const unsigned doy = (153u * mp + 2u) / 5u + d - 1u;
    const unsigned doe = yoe * 365u + yoe / 4u - yoe / 100u + doy;
    return static_cast<int64_t>(era) * 146097 + static_cast<int64_t>(doe) - 719468;
}
 
[[nodiscard]] inline bool is_leap_year(int y) noexcept {
    return (y % 4 == 0 && y % 100 != 0) || (y % 400 == 0);
}
 
[[nodiscard]] inline bool parse_iso_date_to_epoch_day(const std::string& iso,
                                                       int64_t& out_day) {
    if (iso.size() != 10 || iso[4] != '-' || iso[7] != '-') return false;
 
    auto parse_two = [&](size_t idx, int& out) -> bool {
        if (!std::isdigit(static_cast<unsigned char>(iso[idx])) ||
            !std::isdigit(static_cast<unsigned char>(iso[idx + 1]))) {
            return false;
        }
        out = (iso[idx] - '0') * 10 + (iso[idx + 1] - '0');
        return true;
    };
 
    int year = 0;
    for (size_t i = 0; i < 4; ++i) {
        if (!std::isdigit(static_cast<unsigned char>(iso[i]))) return false;
        year = year * 10 + (iso[i] - '0');
    }
 
    int month = 0;
    int day = 0;
    if (!parse_two(5, month) || !parse_two(8, day)) return false;
    if (month < 1 || month > 12) return false;
 
    static constexpr int kMonthDays[] = {31,28,31,30,31,30,31,31,30,31,30,31};
    int max_day = kMonthDays[month - 1];
    if (month == 2 && is_leap_year(year)) max_day = 29;
    if (day < 1 || day > max_day) return false;
 
    out_day = days_from_civil(year, static_cast<unsigned>(month), static_cast<unsigned>(day));
    return true;
}
 
[[nodiscard]] inline int64_t current_epoch_day_utc() {
    using namespace std::chrono;
    const auto now_days = floor<days>(system_clock::now());
    return now_days.time_since_epoch().count();
}
 
[[nodiscard]] inline int current_month_tag_utc() {
    using namespace std::chrono;
    const auto now_days = floor<days>(system_clock::now());
    const year_month_day ymd{now_days};
    return static_cast<int>(static_cast<int>(ymd.year()) * 100 +
                            static_cast<unsigned>(ymd.month()));
}
 
[[nodiscard]] inline std::string default_usage_state_path() {
    // Prefer XDG_STATE_HOME (e.g. ~/.local/state)
    const char* xdg = std::getenv("XDG_STATE_HOME");
    if (xdg && xdg[0]) {
        return std::string(xdg) + "/signet-forge/usage_state";
    }
    // Fall back to HOME-based path
    const char* home = std::getenv("HOME");
#ifdef _WIN32
    if (!home || !home[0]) home = std::getenv("USERPROFILE");
#endif
    if (home && home[0]) {
        return std::string(home) + "/.local/state/signet-forge/usage_state";
    }
    // Last resort: /tmp (less secure but functional)
#if defined(SIGNET_COMMERCIAL_LICENSE_HASH_U64)
    char buf[96];
    std::snprintf(buf, sizeof(buf),
                  "/tmp/signet_commercial_usage_%016llx.state",
                  static_cast<unsigned long long>(
                      static_cast<uint64_t>(SIGNET_COMMERCIAL_LICENSE_HASH_U64)));
    return std::string(buf);
#else
    return "/tmp/signet_commercial_usage.state";
#endif
}
 
[[nodiscard]] inline std::string usage_state_path() {
    return default_usage_state_path();
}
 
[[nodiscard]] inline std::string detect_runtime_user() {
#if defined(SIGNET_ALLOW_RUNTIME_IDENTITY_ENV) && SIGNET_ALLOW_RUNTIME_IDENTITY_ENV
    const char* env_user = std::getenv(kRuntimeUserEnvVar);
    if (env_user != nullptr && env_user[0] != '\0') {
        return sanitize_identity(std::string(env_user), "unknown-user");
    }
#endif
 
#ifndef _WIN32
    struct passwd pwd_buf {};
    struct passwd* pwd = nullptr;
    char storage[4096] = {};
    if (::getpwuid_r(::geteuid(), &pwd_buf, storage, sizeof(storage), &pwd) == 0 &&
        pwd != nullptr && pwd->pw_name != nullptr && pwd->pw_name[0] != '\0') {
        return sanitize_identity(std::string(pwd->pw_name), "unknown-user");
    }
 
    const char* user = std::getenv("USER");
    if (user == nullptr || user[0] == '\0') {
        user = std::getenv("LOGNAME");
    }
#else
    const char* user = std::getenv("USERNAME");
#endif
    return sanitize_identity(user ? std::string(user) : std::string(), "unknown-user");
}
 
[[nodiscard]] inline std::string detect_runtime_node() {
#if defined(SIGNET_ALLOW_RUNTIME_IDENTITY_ENV) && SIGNET_ALLOW_RUNTIME_IDENTITY_ENV
    const char* env_node = std::getenv(kRuntimeNodeEnvVar);
    if (env_node != nullptr && env_node[0] != '\0') {
        return sanitize_identity(std::string(env_node), "unknown-node");
    }
#endif
 
#ifndef _WIN32
    char host[256] = {};
    if (::gethostname(host, sizeof(host) - 1) == 0) {
        host[sizeof(host) - 1] = '\0';
        return sanitize_identity(std::string(host), "unknown-node");
    }
    const char* node = std::getenv("HOSTNAME");
#else
    const char* node = std::getenv("COMPUTERNAME");
#endif
    return sanitize_identity(node ? std::string(node) : std::string(), "unknown-node");
}
 
[[nodiscard]] inline std::vector<std::string> split_csv(const std::string& text) {
    std::vector<std::string> out;
    std::stringstream ss(text);
    std::string token;
 
    while (std::getline(ss, token, ',')) {
        token = sanitize_identity(token, "");
        if (!token.empty()) {
            out.push_back(token);
        }
    }
 
    return out;
}
 
[[nodiscard]] inline std::string join_set_csv(const std::unordered_set<std::string>& values) {
    std::vector<std::string> ordered;
    ordered.reserve(values.size());
    for (const auto& v : values) {
        ordered.push_back(v);
    }
    std::sort(ordered.begin(), ordered.end());
 
    std::string out;
    for (size_t i = 0; i < ordered.size(); ++i) {
        if (i != 0) out.push_back(',');
        out += ordered[i];
    }
    return out;
}
 
inline void load_usage_state_from_file(const std::string& path, UsageState& st) {
    std::ifstream in(path);
    if (!in.good()) {
        return;
    }
 
    std::string line;
    while (std::getline(in, line)) {
        auto eq = line.find('=');
        if (eq == std::string::npos) continue;
 
        const std::string key = trim_copy(line.substr(0, eq));
        const std::string val = trim_copy(line.substr(eq + 1));
 
        uint64_t u64 = 0;
        if (key == "month_tag" && parse_u64(val, u64)) {
            st.month_tag = static_cast<int>(u64);
        } else if (key == "rows_this_month" && parse_u64(val, u64)) {
            st.rows_this_month = u64;
        } else if (key == "eval_start_day_utc" && parse_u64(val, u64)) {
            st.eval_start_day_utc = static_cast<int64_t>(u64);
        } else if (key == "warn_pct_1_emitted") {
            st.warn_pct_1_emitted = (val == "1");
        } else if (key == "warn_pct_2_emitted") {
            st.warn_pct_2_emitted = (val == "1");
        } else if (key == "users") {
            for (auto& token : split_csv(val)) {
                st.users.insert(token);
            }
        } else if (key == "nodes") {
            for (auto& token : split_csv(val)) {
                st.nodes.insert(token);
            }
        }
    }
 
    st.last_persisted_rows_this_month = st.rows_this_month;
}
 
[[nodiscard]] inline bool persist_usage_state_to_file(const std::string& path,
                                                      UsageState& st) {
    const std::string tmp_path = path + ".tmp";
 
#ifndef _WIN32
    // CWE-59: Improper Link Resolution Before File Access
    // Refuse to write through symlinks — lstat() detects symlinks without following them.
    struct stat st_link;
    if (::lstat(tmp_path.c_str(), &st_link) == 0 && S_ISLNK(st_link.st_mode)) {
        return false;
    }
    if (::lstat(path.c_str(), &st_link) == 0 && S_ISLNK(st_link.st_mode)) {
        return false;
    }
#endif
 
    std::ofstream out;
#ifndef _WIN32
    // CWE-732: Create with explicit 0600 permissions to prevent world-readable state files.
    int sfd = ::open(tmp_path.c_str(), O_WRONLY | O_CREAT | O_TRUNC, 0600);
    if (sfd < 0) return false;
    // Wrap the fd in a stdio FILE*, then attach to ofstream via the path
    // (fd ownership: we close it after ofstream opens the same path).
    ::close(sfd);
    out.open(tmp_path, std::ios::out | std::ios::trunc);
#else
    out.open(tmp_path, std::ios::out | std::ios::trunc);
#endif
    if (!out.is_open()) return false;
 
    out << "month_tag=" << st.month_tag << '\n';
    out << "rows_this_month=" << st.rows_this_month << '\n';
    out << "eval_start_day_utc=" << st.eval_start_day_utc << '\n';
    out << "warn_pct_1_emitted=" << (st.warn_pct_1_emitted ? 1 : 0) << '\n';
    out << "warn_pct_2_emitted=" << (st.warn_pct_2_emitted ? 1 : 0) << '\n';
    out << "users=" << join_set_csv(st.users) << '\n';
    out << "nodes=" << join_set_csv(st.nodes) << '\n';
 
    out.close();
    if (!out) {
        std::remove(tmp_path.c_str());
        return false;
    }
 
    if (std::rename(tmp_path.c_str(), path.c_str()) != 0) {
        std::remove(tmp_path.c_str());
        return false;
    }
 
    st.last_persisted_rows_this_month = st.rows_this_month;
    return true;
}
 
[[nodiscard]] inline LicensePolicy resolve_policy() {
    LicensePolicy policy;
 
    const char* license_key = std::getenv(kLicenseEnvVar);
    const auto claims = parse_claims(license_key ? std::string(license_key) : std::string());
 
    std::string tier;
    if (auto it = claims.find("tier"); it != claims.end()) {
        tier = to_lower_ascii(it->second);
    } else {
        const char* env_tier = std::getenv(kLicenseTierEnvVar);
        if (env_tier != nullptr && env_tier[0] != '\0') {
            tier = to_lower_ascii(env_tier);
        }
    }
 
    policy.evaluation_mode =
        (tier == "eval" || tier == "evaluation" || tier == "trial" ||
         tier == "testing" || tier == "test");
 
    if (!policy.evaluation_mode) {
        return policy;
    }
 
    policy.max_rows_month = kDefaultEvalMaxRowsMonth;
    policy.max_users = kDefaultEvalMaxUsers;
    policy.max_nodes = kDefaultEvalMaxNodes;
    policy.max_eval_days = kDefaultEvalMaxDays;
    policy.warn_pct_1 = kDefaultEvalWarnPct1;
    policy.warn_pct_2 = kDefaultEvalWarnPct2;
 
    auto set_u64 = [&](const char* key, uint64_t& out) {
        if (auto it = claims.find(key); it != claims.end()) {
            uint64_t parsed = 0;
            if (parse_u64(it->second, parsed)) out = parsed;
        }
    };
 
    auto set_u32 = [&](const char* key, uint32_t& out) {
        if (auto it = claims.find(key); it != claims.end()) {
            uint32_t parsed = 0;
            if (parse_u32(it->second, parsed)) out = parsed;
        }
    };
 
    set_u64("max_rows_month", policy.max_rows_month);
    set_u64("rows_month", policy.max_rows_month);
    set_u32("max_users", policy.max_users);
    set_u32("max_nodes", policy.max_nodes);
    set_u32("max_days", policy.max_eval_days);
    set_u32("warn_pct_1", policy.warn_pct_1);
    set_u32("warn_pct_2", policy.warn_pct_2);
 
    if (auto it = claims.find("expires_at"); it != claims.end()) {
        int64_t day = 0;
        if (parse_iso_date_to_epoch_day(it->second, day)) {
            policy.explicit_expiry_day_utc = day;
        }
    }
 
    if (policy.warn_pct_1 > 100u) policy.warn_pct_1 = 100u;
    if (policy.warn_pct_2 > 100u) policy.warn_pct_2 = 100u;
    if (policy.warn_pct_1 > policy.warn_pct_2) {
        std::swap(policy.warn_pct_1, policy.warn_pct_2);
    }
 
    return policy;
}
 
[[nodiscard]] inline expected<void> validate_license_once() {
#if !defined(SIGNET_ENABLE_COMMERCIAL) || !SIGNET_ENABLE_COMMERCIAL
    return Error{ErrorCode::LICENSE_ERROR,
                 "commercial feature disabled in this Apache build; "
                 "rebuild with -DSIGNET_ENABLE_COMMERCIAL=ON (AGPL-3.0 commercial tier)"};
#else
#  if defined(SIGNET_REQUIRE_COMMERCIAL_LICENSE) && SIGNET_REQUIRE_COMMERCIAL_LICENSE
#    if !defined(SIGNET_COMMERCIAL_LICENSE_HASH_U64)
    return Error{ErrorCode::LICENSE_ERROR,
                 "commercial tier misconfigured: missing SIGNET_COMMERCIAL_LICENSE_HASH_U64"};
#    else
    const char* license_key = std::getenv(kLicenseEnvVar);
    if (license_key == nullptr || license_key[0] == '\0') {
        return Error{ErrorCode::LICENSE_ERROR,
                     std::string("missing runtime license key: set ") + kLicenseEnvVar};
    }
 
    constexpr uint64_t kExpectedHash =
        static_cast<uint64_t>(SIGNET_COMMERCIAL_LICENSE_HASH_U64);
    const uint64_t actual_hash = fnv1a64(license_key, std::strlen(license_key));
 
    if (actual_hash != kExpectedHash) {
        return Error{ErrorCode::LICENSE_ERROR,
                     std::string("invalid runtime license key in ") + kLicenseEnvVar};
    }
#    endif
#  endif
 
    return expected<void>{};
#endif
}
 
inline std::mutex& usage_state_mutex() {
    static std::mutex m;
    return m;
}
 
inline UsageState& usage_state() {
    static UsageState s;
    return s;
}
 
inline void ensure_usage_state_loaded_locked(UsageState& st) {
    if (st.initialized) return;
 
    load_usage_state_from_file(usage_state_path(), st);
    if (st.month_tag == 0) {
        st.month_tag = current_month_tag_utc();
    }
    st.initialized = true;
}
 
[[nodiscard]] inline expected<void> enforce_eval_limits(const char* feature_name,
                                                        uint64_t rows_increment) {
    static const LicensePolicy policy = resolve_policy();
    if (!policy.evaluation_mode) {
        return expected<void>{};
    }
 
    std::lock_guard<std::mutex> lock(usage_state_mutex());
    UsageState& st = usage_state();
    ensure_usage_state_loaded_locked(st);
 
    bool persist_required = false;
 
    const int current_month = current_month_tag_utc();
    if (st.month_tag != current_month) {
        st.month_tag = current_month;
        st.rows_this_month = 0;
        st.last_persisted_rows_this_month = 0;
        st.warn_pct_1_emitted = false;
        st.warn_pct_2_emitted = false;
        persist_required = true;
    }
 
    const int64_t today = current_epoch_day_utc();
 
    if (policy.max_eval_days > 0 && st.eval_start_day_utc == 0) {
        st.eval_start_day_utc = today;
        persist_required = true;
    }
 
    int64_t expiry_day = policy.explicit_expiry_day_utc;
    if (expiry_day == 0 && policy.max_eval_days > 0 && st.eval_start_day_utc > 0) {
        expiry_day = st.eval_start_day_utc + static_cast<int64_t>(policy.max_eval_days) - 1;
    }
 
    if (expiry_day > 0 && today > expiry_day) {
        return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                     std::string(feature_name) +
                     ": evaluation period expired; commercial license required"};
    }
 
    const std::string user_id = detect_runtime_user();
    if (st.users.insert(user_id).second) {
        persist_required = true;
    }
    if (policy.max_users > 0 && st.users.size() > policy.max_users) {
        return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                     std::string(feature_name) +
                     ": evaluation user threshold exceeded; commercial license required"};
    }
 
    const std::string node_id = detect_runtime_node();
    if (st.nodes.insert(node_id).second) {
        persist_required = true;
    }
    if (policy.max_nodes > 0 && st.nodes.size() > policy.max_nodes) {
        return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                     std::string(feature_name) +
                     ": evaluation node threshold exceeded; commercial license required"};
    }
 
    if (policy.max_rows_month > 0) {
        if (rows_increment > 0) {
            if (st.rows_this_month >
                (std::numeric_limits<uint64_t>::max)() - rows_increment) {
                return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                             std::string(feature_name) +
                             ": usage counter overflow; commercial license required"};
            }
 
            const uint64_t projected = st.rows_this_month + rows_increment;
            if (projected > policy.max_rows_month) {
                return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                             std::string(feature_name) +
                             ": evaluation monthly row threshold exceeded; "
                             "commercial license required"};
            }
 
            st.rows_this_month = projected;
            if ((st.rows_this_month - st.last_persisted_rows_this_month)
                >= kUsagePersistIntervalRows ||
                st.rows_this_month == policy.max_rows_month) {
                persist_required = true;
            }
        } else if (st.rows_this_month >= policy.max_rows_month) {
            return Error{ErrorCode::LICENSE_LIMIT_EXCEEDED,
                         std::string(feature_name) +
                         ": evaluation monthly row threshold reached; "
                         "commercial license required"};
        }
 
        const long double pct =
            (static_cast<long double>(st.rows_this_month) * 100.0L) /
            static_cast<long double>(policy.max_rows_month);
 
        if (policy.warn_pct_1 > 0 && !st.warn_pct_1_emitted &&
            pct >= static_cast<long double>(policy.warn_pct_1)) {
            std::fprintf(stderr,
                         "signet commercial eval warning: %.2Lf%% of monthly row "
                         "limit used (%llu/%llu)\n",
                         pct,
                         static_cast<unsigned long long>(st.rows_this_month),
                         static_cast<unsigned long long>(policy.max_rows_month));
            st.warn_pct_1_emitted = true;
            persist_required = true;
        }
 
        if (policy.warn_pct_2 > 0 && !st.warn_pct_2_emitted &&
            pct >= static_cast<long double>(policy.warn_pct_2)) {
            std::fprintf(stderr,
                         "signet commercial eval warning: %.2Lf%% of monthly row "
                         "limit used (%llu/%llu)\n",
                         pct,
                         static_cast<unsigned long long>(st.rows_this_month),
                         static_cast<unsigned long long>(policy.max_rows_month));
            st.warn_pct_2_emitted = true;
            persist_required = true;
        }
    }
 
    if (persist_required && !persist_usage_state_to_file(usage_state_path(), st)) {
        return Error{ErrorCode::LICENSE_ERROR,
                     std::string(feature_name) +
                     ": unable to persist evaluation usage state"};
    }
 
    return expected<void>{};
}
 
[[nodiscard]] inline expected<void> require_feature(const char* feature_name,
                                                    uint64_t usage_rows = 0) {
    static const expected<void> gate = validate_license_once();
    if (!gate) {
        return Error{gate.error().code,
                     std::string(feature_name) + ": " + gate.error().message};
    }
 
    auto policy_gate = enforce_eval_limits(feature_name, usage_rows);
    if (!policy_gate) {
        return policy_gate.error();
    }
 
    return expected<void>{};
}
 
[[nodiscard]] inline expected<void> record_usage_rows(const char* feature_name,
                                                      uint64_t rows) {
    return require_feature(feature_name, rows);
}
 
} // namespace commercial
 
} // namespace signet::forge