param_contract.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/state/parameter.hpp>
#include <pulp/state/store.hpp>
 
#include <string>
#include <vector>
 
namespace pulp::format::reload {

inline bool param_contract_equal(const state::ParamInfo& a, const state::ParamInfo& b) {
    return a.id == b.id &&
           a.range.min == b.range.min &&
           a.range.max == b.range.max &&
           a.range.default_value == b.range.default_value &&
           a.range.step == b.range.step &&
           a.range.skew == b.range.skew &&
           a.range.symmetric_skew == b.range.symmetric_skew &&
           a.is_trigger == b.is_trigger &&
           // Designation (Bypass / Reset / None) changes how the host and
           // adapters interpret the value per block, so it is part of the
           // contract alongside is_trigger.
           a.designation == b.designation;
}

inline bool has_unique_param_ids(const state::StateStore& store) {
    const auto params = store.all_params();
    for (std::size_t i = 0; i < params.size(); ++i)
        for (std::size_t j = i + 1; j < params.size(); ++j)
            if (params[i].id == params[j].id) return false;
    return true;
}

inline std::vector<std::string> param_contract_diff(const state::StateStore& live,
                                                    const state::StateStore& candidate) {
    std::vector<std::string> out;
    // Bypass parameters are excluded from the contract: an adapter SYNTHESIZES a
    // bypass into the live store to satisfy a host bypass convention (VST3/AU/CLAP
    // via HostQuirks::synthesize_bypass_parameter, quirk_apply.hpp), so the live
    // store carries a bypass the reloaded logic's define_parameters() never
    // declares. Comparing it would make EVERY in-DAW reload of such a plugin fail
    // "contract differs" (the reload the standalone/capture host accepts) even
    // though the logic's automatable surface is unchanged. The adapter owns the
    // bypass independently of the logic, so it is not part of the swap contract.
    // RESIDUAL (low, inherent): the synthesized bypass is created with default
    // designation (None) + a boolean "Bypass" name/range (quirk_apply.hpp), so it
    // is only detectable via the is_bypass_param HEURISTIC. A plugin author's OWN
    // genuinely-automatable boolean param literally named "Bypass" with range
    // [0,1] is therefore indistinguishable and also excluded — its re-ID/removal
    // across a reload is not caught. Requires that exact name+range collision on
    // one param; the fix if it ever bites is to key exclusion on a dedicated
    // "adapter-synthesized" flag instead of the heuristic.
    for (const auto& l : live.all_params()) {
        const state::ParamInfo* c = candidate.info(l.id);
        if (!c) {
            // A bypass present in live but not the candidate is adapter-owned
            // (synthesized) — its absence in the logic's contract is not a
            // violation. A non-bypass removal still breaks automation.
            if (state::is_bypass_param(l)) continue;
            out.push_back("parameter " + std::to_string(l.id) + " ('" + l.name +
                          "') removed in candidate");
        } else if (!param_contract_equal(l, *c)) {
            // Present on BOTH sides → still compared (a real bypass whose range/
            // flags changed is a genuine contract change).
            out.push_back("parameter " + std::to_string(l.id) + " ('" + l.name +
                          "') range/flags changed");
        }
    }
    for (const auto& c : candidate.all_params()) {
        if (!live.info(c.id)) {
            if (state::is_bypass_param(c)) continue;  // candidate-only bypass is adapter-ownable
            out.push_back("parameter " + std::to_string(c.id) + " ('" + c.name +
                          "') added in candidate");
        }
    }
    return out;
}

inline std::size_t contract_param_count(const state::StateStore& store) {
    std::size_t n = 0;
    for (const auto& p : store.all_params())
        if (!state::is_bypass_param(p)) ++n;
    return n;
}

inline bool param_contracts_match(const state::StateStore& live,
                                   const state::StateStore& candidate) {
    // Fail closed on duplicate IDs: with duplicates the size + set-membership
    // checks below can't distinguish multisets (e.g. {1,1,2} vs {1,2,2}), so a
    // duplicate-ID store (a plugin bug) must force a full reload, not hot-swap.
    return has_unique_param_ids(live) && has_unique_param_ids(candidate) &&
           contract_param_count(live) == contract_param_count(candidate) &&
           param_contract_diff(live, candidate).empty();
}

struct ParamSupersetResult {
    bool is_superset = false;                
    std::vector<state::ParamID> added_ids;   
};

inline ParamSupersetResult param_contract_superset(const state::StateStore& live,
                                                    const state::StateStore& candidate) {
    ParamSupersetResult result;
    if (!has_unique_param_ids(live) || !has_unique_param_ids(candidate))
        return result;  // is_superset stays false
    // Every live parameter must survive unchanged in the candidate — a removed or
    // re-ranged/re-flagged parameter would break automation, so it is NOT a
    // superset (that case still requires a full reload).
    for (const auto& l : live.all_params()) {
        if (state::is_bypass_param(l)) continue;  // adapter-owned; see param_contract_diff
        const state::ParamInfo* c = candidate.info(l.id);
        if (!c || !param_contract_equal(l, *c))
            return result;
    }
    // Collect the parameters the candidate adds (present in candidate, not live).
    for (const auto& c : candidate.all_params()) {
        if (state::is_bypass_param(c)) continue;
        if (!live.info(c.id))
            result.added_ids.push_back(c.id);
    }
    result.is_superset = true;
    return result;
}

inline std::size_t carry_state(const state::StateStore& live, state::StateStore& candidate) {
    std::size_t carried = 0;
    for (const auto& l : live.all_params()) {
        if (candidate.info(l.id)) {
            candidate.set_value(l.id, live.get_value(l.id));
            ++carried;
        }
    }
    return carried;
}
 
} // namespace pulp::format::reload