host_quirks.hpp File Reference

Per-host accommodation flags consumed by format adapters. More...

#include <pulp/format/host_type.hpp>
#include <pulp/format/host_version.hpp>
#include <optional>
#include <string_view>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::format::HostQuirks
	Always-on / host-gated defensive behaviors that the adapters consult. More...
struct	pulp::format::HostQuirksMeta
	Per-quirk validation status, parallel to HostQuirks. More...
struct	pulp::format::QuirkFilter
	Selection of validation tiers a HostQuirks instance may keep. More...
struct	pulp::format::ResolvedQuirkPolicy
	The runtime-resolved base filter together with its source. More...
struct	pulp::format::QuirkFieldStatus
	One row of resolved quirk state, for diagnostics (pulp doctor). More...

Namespaces
namespace	pulp
namespace	pulp::format
	What the product grants a device: the quota table indexed by capability tier and live thermal state.

Enumerations
enum class	pulp::format::QuirkStatus : unsigned char { pulp::format::Validated , pulp::format::Speculative , pulp::format::LessonOnly }
	Validation tier for an individual host-quirk flag. See file header. More...
enum class	pulp::format::QuirkPolicySource : unsigned char { pulp::format::CompileDefault , pulp::format::Environment , pulp::format::Api }
	Where the effective base tier-filter came from (for diagnostics — pulp doctor reports this). More...

Functions
void	pulp::format::apply_filter (HostQuirks &q, QuirkFilter filter)
	In-place: zero out (reset to default) every field in q whose meta tier is not allowed by filter.
HostQuirks	pulp::format::make_quirks_for (HostType type, HostVersion version)
	Build a HostQuirks populated for the given host + version.
HostQuirks	pulp::format::make_quirks_for_validated_only (HostType type, HostVersion version)
	Same as make_quirks_for(...) followed by apply_filter(..., kQuirkFilterValidatedOnly).
HostQuirks	pulp::format::detect_quirks ()
	Convenience: detect host + version, return the corresponding quirks.
ResolvedQuirkPolicy	pulp::format::resolve_quirk_policy ()
	Resolve the effective base tier-filter at runtime (does NOT apply per-quirk overrides — those layer on inside resolved_quirks).
void	pulp::format::set_host_quirk_policy (std::optional< QuirkFilter > filter)
	Programmatically set the base tier-filter (highest base-layer precedence, above the env var).
void	pulp::format::set_quirk_override (std::string_view flag, bool enabled)
	Force a single quirk flag on or off by its HostQuirks field name, overriding the tier filter for just that flag.
void	pulp::format::clear_quirk_overrides ()
	Clear all per-quirk overrides set via set_quirk_override.
std::vector< QuirkFieldStatus >	pulp::format::enumerate_quirk_fields (const HostQuirks &q)
	Enumerate every quirk field of q with its tier and whether it is currently enforced, in HostQuirks declaration order.
HostQuirks	pulp::format::resolved_quirks (HostType type, HostVersion version)
	The single entry adapters consume: build the host's quirks, apply the runtime base filter (resolve_quirk_policy), then layer per-quirk overrides.
constexpr int	pulp::format::reported_latency_samples (int raw, const HostQuirks &q) noexcept
	Apply clamp_latency_to_nonneg to a raw Processor::latency_samples() value before reporting it to the host.

Variables
constexpr HostQuirksMeta	pulp::format::kHostQuirksMeta {}
	Authoritative meta for the in-tree HostQuirks.
constexpr QuirkFilter	pulp::format::kQuirkFilterValidatedOnly
	Filter constant: keep only Validated tier accommodations.
constexpr QuirkFilter	pulp::format::kQuirkFilterOff
	Filter constant: drop every accommodation (including cheap defenses).

Detailed Description

Per-host accommodation flags consumed by format adapters.

Pulp's format adapters (VST3, AU v2, AU v3, CLAP, AAX) consult a HostQuirks struct at init time to switch between defensive defaults (always-on) and host-gated behaviors (only when a specific DAW / version is detected). The full catalog of accommodations lives in core/format/host-quirks.json.

Cheap defenses are always-on, and expensive defenses are host-gated. Always-on defaults are seeded by the default-constructed HostQuirks; host-gated flags are turned on by the per-host factory headers under host_quirks/<host>.hpp.

License-hygiene contract: every fix that flips a host-gated flag must cite a host vendor doc + a reproducer Pulp issue. The commit trailer Reference-Lineage: independent reproducer=#NNNN docs=<url> is required (advisory pre-push warning hint will catch missing trailers on commits touching core/format/host_quirks/).

Per-quirk validation tiers

Not every quirk has been bench-validated against a real DAW. We tag each flag with one of three QuirkStatus tiers so plugin authors can dial in exactly the accommodations they trust:

• Validated — exercised against the named DAW under a Pulp regression test that observed the symptom + the fix.
• Speculative — implemented per host docs + reproducer report but not yet confirmed in-DAW from a Pulp test bench. Default ON when the host is detected, but a plugin author can opt out via QuirkFilter{ .allow_speculative = false }.
• LessonOnly — the quirk row exists in the catalog as a historical lesson; no Pulp fix is wired yet. Carried so the enum + meta stay consistent with the catalog (the field's default in HostQuirks is the safe value).

See docs/reference/host-quirks-policy.md for the full opt-in / opt-out story (plugin-author surface) and core/format/host-quirks.json for the current catalog.