param_ordering.hpp File Reference

Cross-version parameter-ordering guard. More...

#include <pulp/state/parameter.hpp>
#include <pulp/state/store.hpp>
#include <cstddef>
#include <span>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::state::ParamOrderingViolation
	One way a new descriptor version broke a previously-shipped parameter's host-facing identity. More...

Namespaces
namespace	pulp
namespace	pulp::state
	SequencerStateChannel is the audio-safe transport for a plugin's structured NON-parameter state: the bulk, observable state a step sequencer / mod-matrix / pattern engine holds outside its automatable parameter set (e.g.

Functions
std::vector< ParamOrderingViolation >	pulp::state::diff_param_ordering (std::span< const ParamInfo > old_params, std::span< const ParamInfo > new_params)
	Diff two parameter descriptors (old vs new) and return every ordering / identity violation, in old-version index order.
std::vector< ParamOrderingViolation >	pulp::state::diff_param_ordering (const StateStore &old_store, const StateStore &new_store)
	StateStore convenience overload.
bool	pulp::state::param_ordering_stable (std::span< const ParamInfo > old_params, std::span< const ParamInfo > new_params)
	True iff new_params is an append-only, identity-preserving evolution of old_params (no re-order, re-ID, or removal of a shipped parameter).
bool	pulp::state::param_ordering_stable (const StateStore &old_store, const StateStore &new_store)
	StateStore convenience overload.

Detailed Description

Cross-version parameter-ordering guard.

A plugin's host-facing parameter identity must stay stable across releases: a DAW session, a saved preset, and a host automation lane are all keyed to a parameter's host-facing ID, and generic/host editors present parameters in index (registration) order. Re-ordering, re-ID'ing, or dropping a previously-shipped parameter silently remaps or clips automation that users already recorded.

The host-facing ID is the same value in every format Pulp targets, because state::ParamID maps 1:1 onto each:

• VST3 — Steinberg::Vst::ParameterInfo::id (the automation key; getParameterInfo/getParamStringByValue are all keyed by it).
• AU v2 — AudioUnitParameterID (the inParameterID/inID passed to GetParameterInfo/GetParameter).
• CLAP — clap_param_info_t::id (the stable clap_id; hosts persist automation against it, independent of the get_info index).

All three key automation by ID, so ID stability is the primary invariant. Index stability is the secondary invariant: several host paths (generic editors, VST3 unit ordering, positionally-saved legacy presets) surface parameters in registration order, so a retained ID that moves index is also a user-visible regression. The only always-safe schema evolution is therefore append-only: keep every previously-shipped parameter at its existing index with its existing ID, and add new parameters at the end.

This utility diffs two descriptor versions (two all_params() spans, or two StateStores) and reports every violation of that rule. It is intended for an author-side unit test / CI gate — not the audio path.