How to read this

What Auracle computes, in enough detail to disagree with.

This book is the technical companion to the User Guide. The guide tells you what the instrument does; this tells you how, with the math written out and pointers into the code that implements it.

It is organised as a pipeline, because that is what it is:

$$\text{term} ;\xrightarrow{\text{compile}}; \text{patch} ;\xrightarrow{\text{render}}; \text{audio} ;\xrightarrow{\text{vet}}; \text{audio} ;\xrightarrow{\varphi}; \R^{44} ;\xrightarrow{;u_\theta;}; \R$$

and a loop that closes over it: your answers condition $\theta$, and $\theta$ reshapes how the next term is proposed.

Three commitments

Every number is sourced. Thresholds, dimensions, defaults and step counts are quoted from the code, with the constant named so you can check. Where a figure came out of a measurement, the measurement is named too.

Design and implementation are distinguished. Several things in Auracle are intended as one algorithm and currently implemented as a simpler one. The clearest case is refinement: the design is tempered sequential Monte Carlo, and what ships is a short local Metropolis–Hastings walk. Those pages say so in their first paragraph. See Refinement.

Known weaknesses are stated. Where a coefficient is unidentified, a variance inflation factor is uncomfortably high, or a memory spike is unfixable without forking a dependency, it is written down.

If you read four pages

1. A typed PCFG over patch terms is the representation decision everything else follows from. Because the genome is a typed term rather than a parameter vector or a raw graph, all three levels of evolution (settings, connectivity, module set) live in one object, and every sample is valid by construction.
2. Trace addresses are the naming scheme shared by panel knobs, hand edits, locks, live parameter handles and search proposals. Nothing else stays coherent without it.
3. Utility as a max of experts explains why taste is a maximum over lenses rather than a mixture, and what that buys.
4. The vetting gate explains why randomly composed DSP graphs are safe to put in front of a person.

Conventions

• Code references name the crate and the item: auracle_features::vet::VetConfig. The API documentation has the generated rustdoc for all of them.
• Math follows Notation. $x$ is a patch term, $\varphi(x)$ its feature vector, $\theta$ the taste parameters, $u$ the latent utility.
• Measured claims cite the harness that produced them, usually an example binary such as auracle-session/examples/search_health.rs, runnable from a checkout.

What lives elsewhere

• The generated API documentation is the rustdoc.
• Using the instrument is the User Guide.
• Working on Auracle — layout, the quality bar, the sharp edges, cutting a release — is CONTRIBUTING.md.
• What changed when is CHANGELOG.md.

Design decisions, rejected alternatives, the milestones, the open questions and the directions nobody has raised yet are in this book, under Design. They used to be a DESIGN.md at the repo root, which made the reasoning and the maths it justifies two documents that could disagree.

The two libraries underneath

Auracle is thin on top of two in-house libraries:

• fugue-evo does evolution as Bayesian inference. Priors as probabilistic programs, typed Metropolis–Hastings with automatic reversible jump, grammar-based genetic programming, tempered SMC in trace space. Auracle's grammar is a GenomePrior; its search is fugue-evo's inference machinery with a learned fitness plugged in.
• quiver does modular synthesis. Arrow-style combinators, typed ports (Audio / V-Oct / Gate / CV), patch graphs, headless rendering, first-class WebAssembly. Auracle's genome is a term in quiver's combinator algebra; its "compiler" targets a quiver patch graph.

Where a guarantee comes from one of them, this book says so.

Notation

Fixed throughout. Where a symbol appears in the code under a different name, the code's name is given.

Objects

$\varphi$ is always the concatenation $[\varphi_{\text{audio}} ; \varphi_{\text{struct}}]$, in that order. It is written $\varphi$ rather than $\phi$ throughout; the code's phi is this vector.

The taste model

Search

Conventions

• $\sigma(\cdot)$ is the logistic function $\sigma(v) = 1/(1+e^{-v})$, never a standard deviation. Standard deviations are always subscripted ($\sigma_\theta$) or written as $s$.
• $\log$ is natural. Log-losses are in nats.
• Indices are 0-based, matching the code, including cutpoint indices, which matters for reading the ordinal likelihood.
• Weights $w$ are always normalized unless stated: importance weights sum to one, recency weights are relative to the newest observation being $1$.
• "Standardized" always means after the affine transform in Standardization. The taste model never sees raw $\varphi$; the observation log never stores anything else.

KaTeX macros

Defined in www/reference/book.toml so a symbol cannot mean two things on two pages:

The crates

Core-library-first. Every frontend is a thin shell over the same engine.

crates/
  auracle-grammar    the genome: typed PCFG over quiver combinator terms,
                      trace codec, term → Patch compiler, structural edit ops,
                      rack description, presets
  auracle-features   phrase render → vet → LUFS-normalize → φ extraction
  auracle-taste      max-of-experts utility, three likelihoods, MCMC posterior,
                      standardization, portable profiles
  auracle-session    the two-loop engine: pool, acquisition, refinement,
                      lineage, calibration, persistence, migration
  auracle-wasm       WasmEngine (worker-side brain) + LivePoly (worklet-side
                      instrument)
apps/web             the instrument — vanilla JS, no build step

Dependencies run strictly downward: grammar knows nothing of features, features nothing of taste, taste nothing of the engine. session is the only crate that sees all of them, and wasm is a binding surface with no logic of its own.

auracle-grammar

The representation, and the crate everything else is built on.

genome's codec is the grammar's addressing. It is one scheme rather than two kept in sync, which is what makes a knob turn, a lock and an MH proposal refer to the same thing.

auracle-features

The measurement crate. One render serves three purposes: the vet report, the feature vector, and the audition buffer the user hears.

pipeline::featurize is the whole crate in forty lines, and the order it composes them in matters; see The vetting gate.

auracle-taste

The model. No knowledge of patches at all: it consumes standardized feature vectors and feedback events.

synthetic is not a test helper that happens to live in src/. It validates the taste model against a simulated user with known ground truth: assert the posterior concentrates on $\theta^*$, and that acquisition regret shrinks. That makes the core falsifiable headlessly.

auracle-session

The engine every frontend drives.

auracle-wasm

Two objects, on two threads, and the split matters:

• WasmEngine is the whole auracle-session engine, in a Web Worker. Pool filling, posterior fits, refinement, workbench edits. Nothing real-time.
• LivePoly is the instrument, in an AudioWorklet. It holds $N$ compiled copies of the current patch, via the same compile() path evolution uses, limiter included.

So what you play is not a re-implementation of what was evolved; it is the same compiled artifact. See The web runtime.

apps/web

Vanilla JavaScript, no build step, no framework, no dependencies. Four files carry it: main.js (UI and Web Audio), worker.js (the engine), farm.js (a stateless render worker), live-audio.js (worklet assembly).

Its own architecture notes are in apps/web/README.md; the parts that constrain the engine are in The web runtime.

Foundations, from crates.io

All three come from the registry. To hack on them alongside Auracle, add a [patch.crates-io] block at the bottom of the workspace manifest.

Two build settings worth knowing, both in Cargo.toml:

• Release builds use lto = "fat", codegen-units = 1, panic = "abort". Everything the user waits on is render-bound. panic = "abort" also drops unwinding tables from the wasm bundle. None of these can change float results; only --fast-math-style options could, and none is enabled.
• serde_json with float_roundtrip. The observation log is the profile's source of truth and must reload bit-identically; serde_json's fast float parse can be off by one ULP.

The two loops

A machine-paced loop and a human-paced loop, sharing one observation stream.

┌─ patch loop (fast, silent, machine-paced) ─────────────────┐
│  grammar prior → vet → pool                                │
│  local MH toward π_β: subtree moves → struct-screen →       │
│  render survivors → feature-score                          │
└──────────────┬─────────────────────────────────────────────┘
               │ candidate pool (`pool_size`: 48 by default, 40 in the app)
               ▼
   acquisition: choose what to play
   (uniform by default; BALD selectable)
               │ audition + feedback events
               ▼
┌─ taste loop (slow, human-paced, persistent) ───────────────┐
│  observe events → posterior over (θ, τ, cutpoints)         │
│  persisted across sessions = the user model                │
└──────────────┬─────────────────────────────────────────────┘
               │ θ reshapes the prior's proposal weights
               └──────────────► back into the patch loop

The two loops run at different speeds on purpose. The machine can evaluate thousands of candidates against a learned surrogate silently, and surface only a curated few. That addresses interactive evolution's classic failure mode: the human bottleneck, where a user is asked to rate a whole population per generation and quits from fatigue.

The patch loop

Machine-paced. No human in it.

1. Fill. Sample terms from the grammar prior, compile, render, vet, featurize. Pool target is SessionConfig::pool_size vetted candidates (48 by default, though the web app passes 40 in apps/web/main.js), with at most 400 draws attempted per fill, since vet failures burn attempts.
2. Refine. Once a posterior exists, take the top refine_seeds candidates and run refine_steps Metropolis–Hastings steps from each. Defaults are 10 seeds × 40 steps, both scaled from the palette's operator count so a palette change does not silently change the search's character.
3. Inject. Each surviving child displaces the pool's lowest-utility member. Pinned candidates are exempt.

The 10 × 40 split is measured; moving in either direction is worse.

The taste loop

Human-paced, and persistent across sessions.

1. Observe. Every duel, star, keep/kill and edit claim appends to the observation log, as raw $\varphi$, never standardized. That is what lets the standardizer be re-fit later without invalidating history.
2. Reweight, immediately. Each new observation folds into the existing posterior by importance sampling. Exact, $O(S)$, and it is what makes the next question respond to the last answer.
3. Refit, occasionally. Full MCMC over the log: 10 000 post-warmup steps after 3 000 warmup, thinned to at most 500 retained draws.

The refit trigger is the interesting part. It is not "every $n$ duels": it fires when the reweighted posterior's effective sample size has degraded far enough that resampling was needed. See The posterior.

Where they meet

Acquisition picks what to show you. The taste tilt carries $\theta$ back into the grammar.

The tilt is the part that makes this more than a scored search. The fitted structural coefficients reshape the categorical weights of the grammar the search draws new modules from — and, because the tilted grammar is installed as the prior, of the target it climbs (see Proposals):

$$w'_i ;\propto; w_i \exp(\eta, t_i)$$

with each multiplier clamped to $[\tfrac14, 4]$ so no module kind is ever starved or monopolized. Details and the shrinkage applied to $t_i$ are in Proposals.

So the loop is genuinely closed: your answers change what gets proposed and what the search counts as parsimonious, not only what scores well once proposed.

Why this is preferential Bayesian optimization

There is a latent objective (your utility), an expensive oracle (you), a cheap surrogate (the posterior), and a generator of candidates (the grammar prior plus MH). The acquisition step is where $\theta$'s posterior uncertainty earns its keep: early sessions can ask informative questions (duels the model cannot rank), and a confident model can mostly serve things you will like.

Whether it is worth asking informative questions rather than random ones is an empirical question. See Acquisition.

The gate on all of it

auracle-session's closed-loop test runs the engine against a SyntheticUser with known ground-truth $\theta^*$, end to end through the real grammar → render → vet → feature pipeline, and asserts that the learned taste ranks genuinely preferred patches on top.

It is slow, and it is the only test that can fail when the loop is broken while every component is individually correct.

Trace addresses

The spine. Six subsystems refer to the genome, and they all use this one naming scheme.

A trace address names one probabilistic choice site in the grammar program. Every site in a term has one, and it is derived from the site's position in the tree rather than assigned:

The pattern is <path>#<param> for parameters and <path> for structure. Paths are /-separated child indices from the root; a /m segment enters a modulation slot, and because every modulation key sits below a /m, the child convention is reused there without ambiguity.

What shares it

Six subsystems, one vocabulary. The alternative is three schemes that drift: a UI parameter id, a genome index and a DSP handle, mapped to each other. The drift surfaces as a knob that edits the wrong thing after a structural change.

Why it cannot drift

Because the canonical trace codec is the addressing scheme, not a translation of it. auracle_grammar::genome encodes a PatchTree to a fugue::Trace by walking the tree and emitting exactly the addresses the grammar program samples at. The same walk decodes.

A round-trip property test pins it: encode a random term, decode it, and require the result be identical. If the codec and the grammar ever disagreed about what a site is called, that test fails.

Structure is encoded in its own choices

The reason a tree can live in a flat trace at all: the structure of an execution is determined by the choices the execution makes. The value at node#leaf decides whether node is a source or a processor, which decides whether node/0 exists at all.

That is what lets fugue's generic trace machinery work unchanged: subtree regeneration, subtree-swap crossover, and reversible-jump Metropolis–Hastings all operate on traces without knowing anything about synthesizers. Auracle contributes a grammar; it does not contribute an inference algorithm.

Live parameter handles

When a term is compiled, each continuous parameter site yields a ParamHandle, an atomic the audio thread reads. Turning a knob does two things:

1. Writes the atomic, so the running voices change without a recompile.
2. Writes the genome at the same address, so the edit is real rather than cosmetic.

Both, always. Writing only the atomic gives you a knob whose change disappears on the next patch swap; writing only the genome gives you a knob you have to recompile to hear.

Not every address has a live handle. Structural sites do not, and a few parameters feed compile-time decisions. window.__aur.nonLiveAddrs in the web app is the set that requires a recompile.

Locks, precisely

$\mathcal{L}$ is a set of exact address strings, typically snapshotted from the UI. A proposal $x \to x'$ is rejected if it changes, deletes or creates any address in $\mathcal{L}$.

All three, and the third is the one that is easy to omit. Scanning only the current trace lets a birth at a locked address through while rejecting the death that would undo it. That is an asymmetric constraint region: it breaks detailed balance, makes the exactness argument false, and lets the chain drift into locked structure it can never leave.

One limit: a structural move can grow a brand-new address inside a locked module, present in neither trace, so it cannot be in $\mathcal{L}$. That case is symmetric (unmatched in both directions), so it costs nothing in detailed balance. A lock is a guarantee about addresses, not about subtrees.

Persisted UI state must be JS-owned

A rule from the web app, and it belongs here because it is about this scheme. UI state that persists must be held in JavaScript and never scraped from the DOM at save time. A phantom DOM slider (present but not the live control) once reset a value and poisoned an autosave with it.

The address scheme makes the genome authoritative; the rule keeps the interface from quietly disagreeing with it.

A typed PCFG over patch terms

The genome is a term in quiver's combinator algebra, generated by a probabilistic context-free grammar whose non-terminals are signal kinds.

The representation decision

The genome is a tree: a term in quiver's Layer-1 combinator algebra. It is not a raw patch graph and not a parameter vector, and the patch graph is the compilation target.

Everything follows from this. One representation covers what usually needs three:

A parameter-vector genome cannot change topology. A raw-graph genome can, but most of its mutations produce invalid graphs, so it needs a repair step, which is a second, undocumented grammar. A typed term needs neither: every sampled term compiles to a valid, sound-making patch, because the type system constrains which productions can fire where.

The sorts are quiver's signal kinds: Audio, V/Oct, Gate, CV. Auracle's PatchTree splits into AudioNode and ModNode, and the split is enforced by Rust's own type system: an ill-sorted term is not rejected at runtime; it cannot be constructed.

The grammar as a probabilistic program

PatchGrammarPrior is a fugue program. Every node at tree path $p$ emits real probabilistic choices at path-keyed addresses:

The amplitude envelope is fixed at amp#attack … amp#release.

The three categorical orders (7 sources, 20 processors, 9 modulation kinds) are the persisted wire format, because the codec writes the chosen index into the trace. They are append-only.

Parsimony is the prior, not a penalty

Deeper terms pay more prior mass by construction: each additional level of recursion multiplies in another #leaf Bernoulli that came out "processor", and each processor node draws its own parameters. There is no size penalty term anywhere.

Ad-hoc parsimony penalties are the norm in genetic programming and a persistent source of trouble: they need tuning, they interact badly with fitness scaling, and they leave the target distribution unwritten. Here the target is written down: $\pi_\beta \propto p_{\text{grammar}} \cdot e^{\beta u}$, and $p_{\text{grammar}}$ is exactly the parsimony pressure.

Modulation is a recursive sort

A modulation input does not take "an LFO". It takes a modulation term, which can itself be built from modulation terms:

• Six leaves: LFO, envelope, random (sample-and-hold), envelope follower, Euclidean, step sequencer.
• Op wraps one modulation term: quantize, slew, rectify, hold.
• Pair combines two.

The #mod order is None, Lfo, Env, Rand, Follow, Euclid, Op, Pair, Steps. The step sequencer is a leaf that sits after the two branches, because the order is append-only wire format and it arrived last. So "is this kind a leaf" is a predicate (mod_kind_is_leaf), not an index range: the range it replaced (kind < 6) would have switched the new leaf off at the depth bound along with the branches, and a term forced to bottom out could never have drawn it.

The step sequencer's values are latent

Steps carries eleven continuous sites: #srate, #slen, #sslew, and one per step, #s0 … #s7. Each step value $u_i$ is its own $\mathrm{Uniform}(0,1)$ draw and plays as $(2u_i - 1)\cdot 5\text{ V}$; #slen decides how many of the eight play (2 to 8, seven equal bins of the knob). This is the Mutable Instruments Marbles design, turned into a genome:

• One site, one step. An MH proposal that moves #s3 re-voices step four and nothing else, so evolution edits a pattern the way a hand does.
• Hidden, not deleted. The steps past #slen stay in the trace. A proposal that shortens the pattern and a later one that lengthens it give back the steps that were hidden instead of inventing new ones.

The module behind it is Auracle's own (auracle_grammar::steps::StepsCv) rather than quiver's StepSequencer, whose values are internal state with no ports: every one of the eleven sites is a port driven by a live knob, so a bar drag in the rack is an atomic write, not a recompile. Its clock is free-running (#srate is $0.5\cdot 2^{5x}$ steps per second), and every audition hears it that way; tempo sync is a live-instrument concern and is not in the genome. With the dock's sync on, the live engine snaps each sequencer's rate to the nearest division of the tempo in octaves (straight, triplet or dotted, a quarter-step per beat up to eight) and drives every voice's clock from one transport through a sync port the term never sees (<key>#~sync). The transport restarts on the first key down or on MIDI start, and it counts steps, not bars, so a five-step pattern keeps its polymeter against a four-beat arp.

So s&h rand → quantize → slew is a legal modulation term, and the rack draws the whole chain. Subterms live at <p>/m/0 and <p>/m/1, the same child convention the audio tree uses; it is unambiguous because every modulation key sits below a /m.

Its parsimony pressure is max_mod_depth, and the renormalizations that enforce it live in mod_weights_at: at maximum depth only leaves remain available, and below a processor the "no modulation" option is removed so a slot that must be filled is filled.

A modulation slot hangs off every module with somewhere to send it. The exceptions are the ones without: Noise, whose only site is a colour switch, and Mix / RingMod, whose two inputs are both audio and whose single knob is the blend. Having two audio children is not itself an exception: the four dynamics productions take two subterms and carry a slot as well.

The palette

Forty-three modules: 7 sources, 20 processors, 16 modulators.

sources     Vco  Supersaw  NoiseGenerator  Wavetable  KarplusStrong  FormantOsc
            Silence
processors  Mix  Filter  Fold  Delay  Chorus  Reverb  Distortion  Bitcrush
            Phaser  RingMod  Flanger  Tremolo  Vibrato  Eq  Granular  Shift
            Comp  Duck  Gate  Vocoder
modulators  Lfo  Adsr  SampleAndHold  SlewLimiter  EnvelopeFollower  …
            StepsCv (Auracle's own: a step sequencer whose values are ports)

Six processors are binary:

A compressor's sidechain is not an audio input, and the type system makes wiring it as one impossible.

What is not in the grammar

Feedback. Terms are acyclic: there are no feedback combinator productions. Modules with internal feedback (delay, chorus, reverb) are fine, and there are plenty of them.

This is a v1 constraint rather than a principle. A tamed feedback production, with a mandatory attenuator and limiter in the loop path, is the intended v2 grammar extension. Until then cycles are unrepresentable, which is why cable dragging in the UI does not offer them.

Strict validation as an oracle

Grammar output is compiled with quiver's ValidationMode::Strict in the test suite. Because the grammar is typed, a SignalMismatch is by construction a bug in our grammar, so Strict doubles as a property-test oracle: sample $N$ terms, compile all of them, and any error fails the test with quiver's actionable message.

Patches are wired in Warn mode, though, with an allowlist test pinning the warning classes. Strict rejects two warning-class pairings the compiler deliberately uses, the clearest being a constant bipolar Offset feeding a unipolar knob. The allowlist test is what keeps "we know about these two" from quietly becoming "we ignore all warnings".

Where this comes from

The design mirrors fugue-evo's ArithmeticGrammarPrior, with quiver signal sorts in place of arithmetic types. That is deliberate: Auracle's genome gets subtree mutation, subtree-swap crossover, reversible-jump MH and tempered SMC from fugue-evo unchanged, because they operate on traces and this genome's trace encoding is faithful.

Parameter sites and their domains

Every continuous knob in the genome is a draw from $\mathrm{Uniform}(0,1)$. The musical meaning is the compiler's job.

One domain, everywhere

pub const PARAM_DOMAIN: std::ops::Range<f64> = 0.0..1.0;
pub const PARAM_MAX: f64 = 1.0 - f64::EPSILON;

pub fn in_domain(v: f64) -> bool {
    v.is_finite() && PARAM_DOMAIN.contains(&v)
}

Every continuous site is normalized to $[0,1)$ and the mapping to Hz, seconds, dB or cents happens in the compiler. Half-open, because that is what $\mathrm{Uniform}(0,1)$ is: fugue's log_prob is $-\infty$ at $x \ge 1$. The domain used to be 0.0..=1.0, which made exactly 1.0 legal here and impossible under the prior — a knob dragged to its stop, two shipped presets and the default vibrato insert all had $\log p = -\infty$, so init_from refused them and ⚡ evolve silently did nothing. Every clamp in the crate now lands on PARAM_MAX, never on 1.0, and it is one f64::EPSILON below rather than the next float down so that a JSON round trip cannot put it back on the boundary. No mapping in the compiler can hear the difference. Three things fall out of the shared domain:

• The prior is trivially correct. $\mathrm{Uniform}(0,1)$ at every site, with no per-parameter range table to get wrong.
• A proposal cannot leave the domain. MH moves are in normalized space.
• The panel can read in musical units (840 Hz, 24 ms, −6.0 dB, +12 ¢) while the genome stays uniform. The knob and the number under it are two representations of the same site.

Note that in_domain requires finite: NaN compares false against every bound, and an infinity is exactly the runaway the gate exists to stop.

Bounded by the mapping

Because the mapping is the compiler's, the musically dangerous regions are excluded by how $[0,1]$ is spent rather than by a downstream guard. Filter resonance maps to a range that stops short of self-oscillation; delay feedback stops short of 1; V/Oct maps into an audible band.

So the grammar cannot express the most degenerate settings at all, which leaves no pathological region for the search to keep sampling and be penalised for.

It is not a substitute for vetting, which catches pathology that arises from composition: a bounded resonant filter fed by a bounded distortion fed by a bounded fold can still scream.

Latent sites

Not every continuous site is heard. A step sequencer (ModNode::Steps, see the grammar) always carries eight step values #s0 … #s7, and #slen decides how many of them play. The rest are latent: in the trace, in the domain, drawn from the prior and moved by MH like any other site, but inert until a longer #slen reveals them.

That is deliberate, and it costs nothing the search has to pay for. A proposal on a latent step changes neither the sound nor $\varphi$, so the tempered target accepts it as a neutral move (drift, not selection: nothing about taste has acted on it yet), and the value it leaves behind is what a later #slen proposal reveals. Shrinking a pattern never throws a step away, and growing it again brings back the step that was there.

Discrete sites

Uniform categoricals, each with a named domain:

Plus the structural categoricals (#src, #op, #mod, #modop, #pairop), whose orders are the persisted wire format and therefore append-only.

Enumerating the sites

domain_violations() returns every out-of-domain continuous site as (address, value), in address order. It reads the trace, not the term:

self.to_trace().choices.iter().filter_map(|(a, c)| match c.value {
    ChoiceValue::F64(v) if !in_domain(v) => Some((a.to_string(), v)),
    _ => None,
})

The trace enumerates exactly the continuous sites, by construction, from the same walk the prior samples. A hand-written match over the productions would be a second table of "which fields are knobs", and the first module somebody forgot to add to it would be the one the next bad value escaped through.

This is the address scheme paying for itself: there is one enumeration of the genome's sites, and it is the one inference uses.

Repair, not refusal

clamp_domains() pulls every out-of-domain site back in and returns how many it fixed. NaN goes to the domain's midpoint; anything else is clamped, with 1.0 and above landing on PARAM_MAX. It runs on every session load, which is what mends a save written by a build that still let a knob rest on the stop.

The asymmetry with the size ceilings is deliberate:

Repair wins for parameters on product grounds: a saved session that already contains a bad value must not become an app the player cannot edit, load, or evolve their way out of. Corruption must not be load-bearing.

The sentinel incident

The gates above are not hypothetical. A shipped session contained amp.sustain = 1e30, an out-of-domain sentinel that had escaped into the genome and then into the observation log.

What one bad cell did:

1. The value rendered fine. The limiter bounds the output, so the audio was unremarkable and vetting passed it. The vet gate is a gate on the sound, not on the term.
2. Its $\varphi$ entered the observation log, with amp_sustain $= 10^{30}$.
3. The standardizer fit on that column produced a mean of $\approx 1.2 \times 10^{29}$ and an SD of $\approx 5.5 \times 10^{29}$, which standardized every real patch in the pool to $-0.2 \pm 10^{-30}$.
4. The coordinate was dead. The model could never learn from it again, and the belief line still printed a contribution for it.
5. The panel read SUSTAIN 1200.0 dB, and the HELD tray printed 1e+30.

The fixes are at three layers:

• clamp_domains on load, which repairs the corruption that exists.
• FeaturizeError::OutOfDomain, which refuses to measure a term whose φ would be a lie, before spending the render. This is the gate that keeps the log clean; every row in the log came through it.
• Runaway-column detection in the standardizer, so the next escape costs a coordinate's precision rather than the coordinate.

Layers 1 and 2 should make layer 3 unnecessary. It exists anyway, because the value got through everything that was supposed to stop it.

Budgets

Separately from domains, the search is bounded in size:

Shown in the app as 8/24 modules · 4/6 depth · 1/3 mod depth. A hand-built patch past a ceiling is refused, and one at a ceiling has no room to grow, which is a common reason a generation reports "no proposal beat its parent". See the validity gate for why the two depth ceilings are derived from the prior rather than set above it.

Structural edits

Hand edits and search proposals walk the same lattice, which is what makes the workbench trustworthy.

The vocabulary

Because the genome is a typed tree, rewiring is a small closed set of operations that are type-safe by construction: an LFO can never end up in an audio slot, and a filter always has exactly one audio input.

Nodes are addressed by trace key: node, node/0, node/0/1, node/0/m.

The *Tree variants exist for the wiring gestures: "plug this staged chain in here". Callers park the displaced subtree client-side, which is what the HELD tray is.

Wrap versus replace

The distinction shows up twice and is the same idea both times:

• Replace on a source with a processor kind wraps the source rather than deleting it, because a processor needs an input and the obvious one is what was already there.
• SetMod with a shaper kind wraps the existing modulation term rather than evicting it, which is what makes s&h rand → quantize → slew a three-click build.

The socket in the UI says which of fill / replace / wrap it is about to do, so the choice is never implicit.

Hand edits and MH proposals are the same moves

These are the operations evolution's structural proposals make. There is no separate mutation vocabulary.

Consequences:

• Anything you can build by hand, the search can reach. Anything the search produces, you can edit.
• A structural edit cannot produce a term the search would consider invalid, because validity is one predicate.
• ⚡ evolve from this on a hand-built patch is not a special case.

Parameter edits

Separately, edit::set_param(tree, addr, value) writes one continuous or discrete site by address. This is what a knob drag is: a one-site write, then a re-render and re-vet before the result can be auditioned.

The validity gate

validate_tree is the predicate every edit result must satisfy, and it is what the structural-edit gate test exercises.

Hard ceilings on hand-built patches:

pub const MAX_SIZE: usize = 24;                            // modules
pub const MAX_DEPTH: usize = PRIOR_MAX_DEPTH + 1;          // audio tree depth: 6
pub const MAX_MOD_DEPTH: usize = PRIOR_MAX_MOD_DEPTH + 1;  // modulation nesting: 3

MAX_SIZE protects the realtime voice and the feature pipeline. The two depth ceilings are derived from the prior's support, and that is a correction: they used to be 9 and 4 against a prior whose max_depth is 5 and max_mod_depth is 2, on the reasoning that a person stacking modules by hand knows what they are building and the ceiling only protects the voice. What that reasoning missed is that the prior forces #leaf at max_depth and zeroes Op/Pair at max_mod_depth, so the deepest term it can score has depth max_depth + 1. A hand edit past that had $\log p = -\infty$, EvolutionChain::init_from returned None, and ⚡ evolve on the patch did nothing and said nothing — the very failure the grammar gives Silence non-zero weight to prevent. Now the ceiling is the support, stated once in prior.rs and read from there.

A session saved under the old ceilings may hold a deeper tree. It still loads and plays — no load path re-checks the ceilings, because corruption must not be load-bearing — but refinement reports it as outside_support rather than pretending to walk, and a structural edit that leaves it over the ceiling is refused until one brings it under.

MAX_MOD_DEPTH stops well short of the audio ceiling for a concrete reason: a Pair branches, so depth 3 is up to eight leaves on one cable, and each is another level of the compiler's by-value recursion stacked on top of the audio tree's. That is a stack-depth argument rather than an aesthetic one; see the wasm stack note.

The gate test

The structural-edit suite is a gate rather than a set of unit assertions:

Apply every operation at every node of randomly generated trees, and require the result to stay compilable.

This catches the class of bug that unit tests miss: an operation that is individually correct but produces an invalid term in combination with a particular tree shape. The codebase leans on gates like this generally; the preference is stated in CONTRIBUTING.md: prefer extending a gate over asserting implementation details.

Naming stability

NodeKind serializes as snake_case, and that string is also what describe::RackModule::kind reports and what the frontend keys its palette off.

RingMod is renamed by hand, because the derived spelling would be ring_mod while the module is ringmod everywhere else, and one module with two spellings is a defect waiting for a caller.

Node identity

Nodes carry a Uid assigned on the way into the pool. This is what makes the rack's hand positions and locks survive a structural edit. Without them a node is its position, so any structural change wipes the locks and destroys the hand-build → pin → breed loop the editor exists to serve.

A node is a thing with an identity that has a position, not a position that has contents.

Compilation to a patch

Term → quiver `Patch`. One path, used by both the search and the live instrument.

auracle_grammar::compile is the largest single module in the workspace, and its job is narrow: turn a PatchTree into a playable quiver patch graph, with handles for every live parameter.

The mandatory output chain

Every compiled voice ends the same way, and none of it is optional:

$$\langle\text{audio}\rangle \to \text{DC blocker} \to \text{VCA (amp ADSR)} \to \text{Limiter} \to \text{StereoOutput}$$

Plus two external controls (pitch in V/Oct and gate in volts) fanned out to every pitched source and every envelope.

No evolved patch can bypass the limiter or end up unplayable. That is safety layer 3, and it is enforced by the compiler emitting the chain, not by asking the grammar not to.

The tail is built once per channel, so a subtree that produces true stereo (reverb, chorus) keeps both tanks all the way to the output rather than having the right one discarded on the way to a mono sum.

Parameter mapping

The compiler owns the musical meaning of every normalized $[0,1]$ site, and the ranges are deliberately bounded away from pathology:

So the grammar cannot express self-oscillating resonance or a runaway delay. This is the same argument as parameter domains, one layer down: excluding a region is better than generating it and rejecting it.

Two details worth knowing when reading the code:

• Some quiver inputs are gates, not amounts. Adsr.shape, Vca.response and Limiter.soft are read at a 2.5 V threshold, so 5 V and 10 V do the same thing. The compiler uses named constants GATE_TRUE = 5.0 / GATE_FALSE = 0.0 rather than bare numbers, because "5.0" at one of those ports does not mean what it looks like.
• Filter keytracking is fixed at 0.5. quiver applies $2^{v \cdot a}$, so 0.5 moves the corner half an octave per octave played: enough that a patch still speaks two octaves above where it was dialled in, which is what the audition phrase's C5 stab measures.

The DC blocker, and makes_dc

The output chain includes a DC blocker, and the compiler decides whether it is needed by walking the term:

fn makes_dc(node: &AudioNode) -> bool {
    match node {
        AudioNode::Filter { kind, input, .. } =>
            matches!(kind, FilterKind::Ladder) || makes_dc(input),
        AudioNode::Distortion { mode, input, .. } =>
            matches!(mode, DriveMode::Tube) || makes_dc(input),
        AudioNode::Mix { a, b, .. } | AudioNode::RingMod { a, b, .. } =>
            makes_dc(a) || makes_dc(b),
        // sources produce none; dynamics inherit from their audio input
        …
    }
}

Two productions generate a DC offset (the ladder filter and tube-mode distortion), and it propagates up through anything downstream of them.

Without the blocker, a tube-drive patch measures 1–8% DC as a fraction of RMS. That is nowhere near the vet gate's 0.6 limit, which is the point worth recording: the vet gate was never what protected the feature extractor from that offset. The blocker was.

Validation mode

Patches are wired under ValidationMode::Warn, not Strict.

quiver's Strict rejects warning-class pairings, and two of them are idioms this compiler leans on deliberately:

• a unipolar modulation envelope driving a bipolar FM input,
• the bipolar pitch Offset driving V/Oct inputs.

The type discipline Strict would enforce is already guaranteed by construction: the term's Audio/Mod sorts are Rust types, and the compiler only emits known-good connection shapes.

Compile errors (invalid ports, cycles) remain hard failures. Accumulated warnings are returned for inspection, and a property test asserts they stay within the expected classes. That test is what stops "we know about these two" from drifting into "we ignore all warnings".

Separately, the grammar's output is compiled under Strict in the test suite, where a SignalMismatch is by construction a bug in the grammar and therefore a useful oracle. Two different modes for two different questions.

Live parameter handles

Compilation returns a ParamMap: address → ParamHandle, each wrapping an AtomicF64 the audio thread reads.

This is what makes knob turns free. Turning a knob writes the atomic, so the running voices change on the next block with no recompile, and writes the genome at the same address. Both, always; see Trace addresses.

Structural changes do require a recompile, and so do the handful of parameters that feed compile-time decisions.

One compiler, two callers

• The search compiles a term to render and measure it.
• LivePoly compiles the same term, through the same function, to play it: $N$ copies for $N$ voices, limiter included.

So what you hear under your fingers is the patch that was evolved, vetted and featurized. There is no separate "playback engine" that could disagree with the one the model learned from.

Cost

The compiler is recursive and builds by value: every level of Compiler::build constructs quiver modules before moving them into the patch, and some of those carry large inline buffers. A PitchShifter holds [f64; 4800], which is 38 KB, and a Granular holds more.

On a native main thread this is invisible. On wasm32, whose default stack is 1 MB, a dozen-module patch overflows it, and it does so as memory access out of bounds, nowhere near the flag that caused it. See the stack size for the fix and why it lives in the Makefile.

The standard phrase

Audio features are only comparable under an identical stimulus. This module owns that stimulus.

The spec

PhraseSpec::default() is four notes, ~5.05 seconds, 44 100 Hz, RNG seed 0xE05_F00D:

Pitches are V/Oct offsets from C4. The seed is installed into quiver's thread-local RNG before rendering, so noise and analog drift are bit-reproducible: a patch's features are the same every time it is measured.

Why each segment

The original phrase was three short notes (0.6 s stab, 0.25 s stab, 0.8 s low note), and it was the loop's weakest link. It could not discriminate

• slow pads: a 2-second attack was silent for most of the stimulus,
• anything modulated below ~1 Hz: no register-constant segment long enough to hold a modulation cycle,
• anything above Eb4, its highest note,
• how a patch stacks polyphonically: it was strictly monophonic.

So the grammar could express patches the audition could never reveal, and the taste model was being asked to learn preferences over evidence that was not in $\varphi$. No amount of model improvement fixes that; it is a measurement problem.

The v2 default covers each hole with the cheapest segment that reveals it:

1. C4 held 1.8 s. The attack measurement window (onset → next onset) is now 2.0 s rather than 0.75 s, and the sustain is long enough that sub-Hz modulation completes most of a cycle. held_centroid_std is measured here specifically, which is what makes it register-constant by construction.
2. C5 stab. One octave above the old ceiling. With the compiler's fixed 0.5 keytracking, this is where dark patches reveal whether they speak up high (high_ratio).
3. C4+E4 dyad. A second compiled voice, gate-synced with the main voice, reveals intermodulation (chord_flatness_delta). A dyad rather than a triad because render cost is per voice-second and pairwise intermodulation is the first-order phenomenon.
4. C3 with a 1.1 s release window, kept last. Bass register, and its position matters: the tail measurement is the final 300 ms, so putting this note last is what makes the tail see release length and reverb rather than a truncated chord decay.

Cost: about 2× the v1 render, measured. The dyad's second voice is the difference between wall seconds and rendered voice-seconds.

Chord voices

Note::chord carries additional simultaneous pitches, each rendered by its own compiled voice, gate-synced with the main note.

Two behaviours worth knowing:

• Chord voices start cold at the note's onset, exactly how live voice allocation behaves, so the measurement matches what a player would hear.
• After the shared gate closes they keep ticking until their own output parks on silence. A truncated release tail is a broadband click, and a click would poison every spectral feature in the frame it lands in.

max_voices() reports the largest simultaneous count (2 for the default spec), and the vet gate's peak ceiling scales with it.

The :p2 stimulus tag

Every audio feature name carries a generation tag:

centroid_mean:p2   rms_std:p2   attack_s:p2   …

This is the migration mechanism, not a version comment.

A stimulus change changes what every audio value means, even when the formula is untouched. A slow pad's rms_mean under a phrase that never lets it open is a different quantity from the same field under one that does. The observation log stores raw $\varphi$ by name, and FitSet::build projects old logs onto the current names on the rule same name ⇒ same coordinate.

So tagging the name with the stimulus generation means votes recorded under the v1 phrase:

• keep their structural coordinates, which are stimulus-independent;
• have their old-stimulus audio coordinates imputed as "no evidence" rather than mixed into a standardizer they were never commensurable with.

Bump the tag whenever PhraseSpec::default() changes audibly. Failing to bump it is worse than a wrong number: it is old evidence presented as current evidence.

What the phrase still does not reveal

Stated because the model cannot learn what the stimulus does not show:

• Velocity response. The phrase plays at one velocity.
• Fast passages. No segment tests how the patch behaves in a run.
• Long-term behaviour. Five seconds cannot reveal a 30-second evolving pad.
• Stereo width. The render is summed to mono for feature extraction, and there is no width coordinate in $\varphi$ at all. The chorus module's spec card says so outright in the app.

The intended direction is per-style audition phrases (a discovered bass style picks a bassline, a pad style picks a chord swell), which would make the stimulus adaptive rather than fixed. That is a design note, not shipped code, and the :p2 tag is the mechanism that would let it happen without invalidating history.

Loudness normalization

Louder reliably wins A/B tests. Without normalization the model would learn "I like loud" and present it as a preference about timbre.

Every render is normalized to −18 LUFS (TARGET_LUFS) before audition and before feature extraction. Unnormalized loudness would poison $\theta$, and it would do so in a way that looks like a real result.

Why LUFS and not RMS

Because the confound is perceived loudness. K-weighting approximates the ear's sensitivity (a high-shelf boost above ~1.7 kHz plus a ~38 Hz highpass), and 400 ms gated blocks keep silence and release tails from dragging the measurement down. Plain RMS would under-measure a bright patch and over-measure a bass-heavy one, and then the "loudness" the model learned about would be a spectral preference in disguise.

The implementation follows ITU-R BS.1770 (auracle_features::loudness).

K-weighting

Two biquads in direct form 1, derived parametrically from the BS.1770 analog prototype by the RBJ bilinear transform, the same approach pyloudnorm takes, so any sample rate works and the coefficients match the spec's published 48 kHz values at 48 kHz.

Stage 1, the high shelf:

$$G = 3.999844\ \text{dB}, \quad Q = 0.707175, \quad f_c = 1681.974\ \text{Hz}$$

Stage 2, the highpass:

$$Q = 0.500327, \quad f_c = 38.1355\ \text{Hz}$$

With $k = \tan(\pi f_c / f_s)$, $V_H = 10^{G/20}$ and $V_B = V_H^{0.499667}$, the shelf's coefficients are

$$a_0 = 1 + \tfrac{k}{Q} + k^2, \qquad b_0 = \frac{V_H + V_B \tfrac{k}{Q} + k^2}{a_0}, \qquad b_1 = \frac{2(k^2 - V_H)}{a_0}, \qquad b_2 = \frac{V_H - V_B \tfrac{k}{Q} + k^2}{a_0}$$

and the highpass is the standard RBJ form. Deriving rather than tabulating is what makes the measurement correct at 44 100 Hz, which is the rate the phrase renders at.

Block loudness and the two gates

Blocks are 400 ms with 75% overlap. Each block's loudness is

$$L_j = -0.691 + 10 \log_{10}!\left(\frac{1}{N}\sum_{n} w[n]^2\right)$$

where $w$ is the K-weighted signal. The $-0.691$ dB offset is the spec's calibration constant.

Then two gates, in order:

1. Absolute gate. Discard blocks with $L_j \le -70$ LUFS. If none survive, the signal is silent and the function returns None.
2. Relative gate. Compute the mean energy of the surviving blocks, and discard blocks more than 10 LU below it: $$\Gamma = -0.691 + 10\log_{10}!\big(\bar{E}_{\text{abs}}\big) - 10$$

The integrated loudness is the same expression over the twice-gated set:

$$L = -0.691 + 10 \log_{10}!\left(\frac{1}{|\mathcal{G}|}\sum_{j \in \mathcal{G}} 10^{(L_j + 0.691)/10}\right)$$

Note that gating averages in the energy domain, not the dB domain, which is why the implementation exponentiates each retained block loudness back before averaging rather than taking a mean of decibels.

The relative gate is what makes this robust for the phrase specifically: the phrase ends with 1.1 seconds of release tail by design, and a plain average would let that tail pull the measurement down and then be compensated for by a boost.

Applying the gain

let wanted_db   = (target_lufs - lufs).min(MAX_GAIN_DB);        // MAX_GAIN_DB = 30.0
let headroom_db = 20.0 * (PEAK_CEILING / peak_before).log10();  // PEAK_CEILING = 1.0
let gain_db     = wanted_db.min(headroom_db);
let gain        = 10f64.powf(gain_db / 20.0);

The boost is capped at +30 dB. A patch needing more than that is a vetting problem, not something to amplify, and vetting runs first, so in practice the cap is a backstop.

Loudness is a target; the peak is a limit

Matching integrated loudness says nothing about the peak, and crest factor spans tens of dB across this grammar — a pad and a pluck at the same LUFS are nowhere near the same peak. A pure loudness match therefore sends percussive patches over full scale, and it did. Measured over 150 vetted prior draws:

The two 22s are the same twenty-two patches, and the unmoved median is the check that this is a fault stop rather than a re-levelling of the pool.

This is not a matter of audio polish. Preference data is elicited on this exact buffer, so a clipped audition collects a vote about clipping rather than about the patch — precisely the confound loudness normalization exists to remove, one stage later and silent. The live voice was never exposed to it; its master limiter has always held a 0.98 ceiling. The offline path took the volt divisor and not the limiter.

A smaller gain, not a limiter. A scalar keeps render_playback bit-identical by construction — the property its bit-identity test exists to protect — and cannot change timbre at all. A limiter would reshape the waveform, moving crest, flatness_mean and flux_mean as well as the RMS pair, and would need a second copy of itself inside the replay path forever.

What it costs is on the record rather than hidden: the ~15% that reach the ceiling audition below target, so loudness matching degrades exactly where crest is highest. Quieter is a smaller bias on a preference judgment than clipped. Features::peak_reduction_db carries the amount, so a surface can say "pulled down 3 dB so it would not clip" instead of presenting a peak-limited patch as merely quiet.

make norm-peak reproduces the table.

The report carries lufs_before, gain_db and peak_reduction_db, all of which survive into Features. They are diagnostics rather than model inputs: they are not coordinates of $\varphi$, because "how quiet was this before we fixed it" is exactly the information normalization exists to discard.

Where it sits in the pipeline

After vetting and before feature extraction:

$$\text{render} \to \text{vet} \to \text{normalize} \to \varphi_{\text{audio}}$$

Vetting inspects the raw render, deliberately: its thresholds are about the patch's real output level, and measuring them post-normalization would make the peak ceiling meaningless. See the order is the design.

The normalized buffer is also exactly what the user hears. One buffer serves the health check, the measurement and the playback, which is what makes "you never hear an unvetted patch" true by construction rather than by discipline.

Mono

The measurement is mono, and so is the buffer $\varphi_{\text{audio}}$ is computed from. A patch that produces true stereo keeps both channels through to the live output, because the compiler builds the tail per channel, but the measurement path sums.

So stereo width is invisible to the model. There is no width coordinate, so no amount of voting can teach a preference for it. The app says so on the chorus module's spec card, and this is why.

The vetting gate

No candidate is ever played live unvetted. This is what makes randomly composed DSP graphs safe to put in front of a person.

Evolution will generate pathological patches: screaming resonance, silent duds, NaN-poisoned state, astronomically high pitches. The gate is what makes that acceptable rather than dangerous.

What it measures

vet(samples, cfg) inspects the raw, pre-normalization render and returns either a report or a quarantine reason.

pub struct VetReport {
    pub peak: f64,             // max |sample|
    pub rms: f64,              // whole-phrase RMS
    pub dc_ratio: f64,         // |mean| / rms
    pub pinned_fraction: f64,  // fraction within 2% of peak
}

Failures, checked in this order:

pinned_fraction, the share of samples within 2% of the peak, is informational only. It indicates heavy limiting, which is a character rather than a fault; promoting it to a failure would quarantine an entire timbre.

The thresholds

impl Default for VetConfig {
    fn default() -> Self {
        Self { rms_floor: 1e-4, peak_ceiling: 2.0, max_dc_ratio: 0.6 }
    }
}

Deliberately lenient. The gate exists to catch pathology, not to encode taste; that is the model's job, and a gate that quietly enforces a preference corrupts the data it protects.

The polyphony-scaled ceiling

VetConfig::for_spec scales the peak ceiling with the phrase's polyphony:

$$\text{ceiling} = 2.0 + 1.5,(V - 1)$$

where $V$ is max_voices(). The default 2.0 is one limiter-bounded voice (~1.5 peak in the ±1.0 float domain) plus overshoot headroom; $N$ gate-synced voices legitimately sum toward $N$× one voice.

Not scaling it would quarantine honest polyphony as runaway, and specifically the dyad segment, which exists to measure that summing. The measurement and the gate have to agree about what stacking is.

The thresholds were re-checked, and did not move

Worth recording, because a gate tuned before a whole family of modules existed is exactly the kind that starts quarantining a timbre.

When the drive modules arrived, the three thresholds were measured over the full cross of {soft, hard, tube} × drive {0.3, 0.6, 0.85, 1.0} × {saw, square, supersaw}, plus a stacked fold → tube drive → resonant ladder chain:

Peak is bounded by construction: quiver's shapers all normalize into the ±1 domain and rescale, so a drive module is bounded at ±5 V however hard it is pushed. Drive buys harmonics, not level.

The DC result is 0.0016 only because compile::makes_dc puts a blocker in front of every tube-mode patch. Without it the same renders measure 1–8%, still nowhere near 0.6. So this gate was never what protected the feature extractor from that offset. A threshold a defect passes comfortably is not a defence against it.

The one threshold that would have had to move, had the shaper not been bounded, is peak_ceiling.

The order is the design

pipeline::featurize composes the stages, and the order matters:

// 1. Domain check — BEFORE the render
if let Some((site, value)) = tree.domain_violations().into_iter().next() {
    return Err(FeaturizeError::OutOfDomain { site, value });
}
// 2. Render
let mut render = render_phrase(tree, spec)?;
// 3. Vet the RAW render
let report = vet(&render.samples, &VetConfig::for_spec(spec))?;
// 4. Normalize
let norm = normalize_to(&mut render.samples, render.sample_rate, TARGET_LUFS)…;
// 5. Extract φ
let audio = audio_features(&render);
let structural = struct_features(tree);
// 6. Non-finite check on the VECTOR
for (name, value) in Features::phi_names().iter().zip(features.phi()) {
    if !value.is_finite() { return Err(FeaturizeError::NonFiniteFeature { … }); }
}

Four things about that order:

The domain check is first, before the render. A term with a knob outside its range is not a candidate that happens to sound bad: it is a term whose $\varphi$ would be a lie, and the ~600 ms render is wasted on it either way. This is the gate that keeps the observation log clean: every row in the log came through here. It is also the gate that was missing when the 1e30 sentinel got in, because vetting is a gate on the sound and amp.sustain = 1e30 renders perfectly well.

Vetting is on the raw render. Its thresholds are about the patch's real output level; measuring peak after normalization would make the ceiling meaningless.

Normalization is before extraction. Otherwise loudness leaks into every amplitude-sensitive coordinate.

There is a second finiteness check, on the vector. It costs one pass over forty-four doubles against a render that took most of a second, and it is the only thing standing between a NaN out of a spectral descriptor and a posterior fit that returns all-NaN $\theta$. It is a different error from OutOfDomain and names the coordinate rather than a genome site, because at that point the term was legal and the measurement went wrong.

Quarantine is not just hiding

A failed candidate is never played and never shown, and it also scores QUARANTINE_FITNESS = -50.0 in the search target.

That is safety layer 2: evolution learns to avoid the pathological region rather than repeatedly sampling it. Hiding alone would leave the search wasting its budget in a place it cannot see is bad.

The five layers, in one place

Two upstream bugs

Both in quiver, both fixed there, and both worth knowing as the class of thing that lurks under randomly composed DSP:

• Q198. Oscillator phase accumulators latched NaN permanently on non-finite pitch (NaN − floor(NaN)), and the while phase >= 1.0 wrap style used by Wavetable and FormantOsc spun the audio thread forever on an infinite increment (voct_to_hz overflows at extreme V/Oct). An infinite loop on the audio thread is not a glitch; it is a dead tab. Fixed with a shared $O(1)$ wrap_phase that recovers non-finite values.
• Q199. Graph scatter now zeroes non-finite module outputs, so one module's NaN/Inf can never poison another module's recursive state through the routing buffers. Containment at the graph boundary; per-module input sanitization remains defence in depth.

Still open upstream, and non-blocking: voct_to_hz is unclamped. Q198 recovers from the overflow rather than preventing it, and a pitch clamp would additionally tame the aliasing garbage that absurd-but-finite pitches produce.

φ_audio — perceptual descriptors

Eighteen dimensions, kept compact and put on axes a linear model can express a preference along.

Computed on Hann-windowed frames of the normalized mono render (2048 samples, 50% hop), plus a few time-domain and segment-local measurements. Every field is finite by construction, because vetting ran first.

The coordinates

The :p2 suffix is the stimulus generation tag, and it is the migration mechanism rather than a comment.

Why these axes and not the obvious ones

The model downstream is linear in $\varphi$, so the axis a feature lives on decides what preferences are expressible at all.

Frequency features are logarithmic, not linear in Hz

Brightness and pitch perception are octave-based. On a linear-Hz axis normalized by Nyquist, moving a patch from 200 Hz to 400 Hz (a full octave, an enormous audible change) shifts the coordinate by 0.009, while 8 kHz → 16 kHz shifts it by 0.36.

A linear model in that coordinate cannot represent "I like my basses a shade brighter": the entire usable range is swallowed by the bright tail of the pool. The preference is not hard to learn, it is inexpressible.

So log_axis puts centroid, rolloff and ZCR on a shared octaves-above-20 Hz scale, normalized to $[0,1]$ at Nyquist:

$$\text{log_axis}(f) = \frac{\log_2!\big(\max(f, f_0)/f_0\big)}{\log_2!\big(\max(f_{\text{Nyq}}, 2f_0)/f_0\big)}, \qquad f_0 = 20\ \text{Hz}$$

20 Hz because below it frequency is not audible as pitch and the ratio scale stops meaning anything. Normalizing at Nyquist keeps the vector sample-rate agnostic.

Note that a zero-crossing rate is a frequency (two crossings per cycle), so it goes on the same axis:

$$\text{zcr_mean} = \text{log_axis}!\left(\frac{r \cdot f_s}{2}\right)$$

where $r$ is the crossing fraction. Leaving it as a raw fraction would put a frequency-like quantity on a non-frequency axis beside three that are on one.

Heavy tails are logged

crest spans 1 to 40+; tail_ratio spans three orders of magnitude. Standardizing either raw hands the model a coordinate whose z-score is near-constant for most of the pool and $+4$ for a handful of outliers: a coordinate that separates nothing except the outliers.

$$\text{crest} = \log!\frac{\text{peak}}{\text{RMS} + \epsilon}, \qquad \text{tail_ratio} = \log!\left(\frac{\text{RMS}_{\text{last 300 ms}}}{\text{RMS} + \epsilon} + 10^{-3}\right)$$

The $10^{-3}$ floor inside the tail log matters: a pluck fully decayed by the last 300 ms would otherwise send the log to $-\infty$, and "silent tail" and "very quiet tail" are the same judgement to a listener anyway.

The attack crossing is interpolated, not floored

Quantizing the 90%-of-peak crossing to the analysis-window index makes attack_s exactly zero for every patch whose first window is already at peak (most percussive patches), turning a continuous axis into a zero-inflated spike.

So the envelope uses a fine grid (4 ms window, 1 ms hop) and interpolates linearly between the last sub-threshold hop and the first one over it:

$$h^\star = (i-1) + \frac{0.9,\max(e) - e_{i-1}}{e_i - e_{i-1}}, \qquad \text{attack_s} = \log!\left(\frac{h^\star \cdot \text{hop}}{f_s} + 0.005\right)$$

The measurement window is onset → the second note's onset (2.0 s under the v2 phrase), and the $+5$ ms inside the log keeps the fast end resolved instead of compressing every percussive patch into the same value.

Spectral definitions

Per frame, with magnitudes $m_i$ over $\text{bins} = 1024$ and $\text{power} = \sum m_i^2$:

Centroid. The magnitude-weighted mean frequency, then log-axised:

$$f_c = \frac{\sum_i i \cdot \Delta f \cdot m_i}{\sum_i m_i}$$

Rolloff. The lowest bin at which cumulative power reaches 85% of the total.

Flatness. Geometric over arithmetic mean of the power spectrum, clamped to 1:

$$\text{flatness} = \min!\left(1,\ \frac{\exp!\big(\tfrac{1}{N}\sum_i \log(m_i^2 + \epsilon)\big)}{\tfrac{1}{N}\sum_i m_i^2 + \epsilon}\right)$$

Flux. Normalized by the combined magnitude sum of both frames:

$$\text{flux} = \frac{\lVert m^{(t)} - m^{(t-1)} \rVert_2}{\sum_i m^{(t)}_i + \sum_i m^{(t-1)}_i + \epsilon}$$

Dividing by the current frame alone is the obvious choice and it explodes: a loud frame decaying into near-silence gives an enormous flux for a change that is barely audible. The combined denominator keeps it in roughly $[0,1]$.

Frames whose power is below $10^{-12}$ contribute to none of the spectral means: a silent frame has no centroid, and averaging in a zero would drag brightness down in proportion to how much silence the phrase happens to contain.

Segment-local coordinates

The last three are measured over one note's gate-on span, and they exist because whole-phrase statistics conflate things a listener does not.

Roles are found by property, not position, which is what keeps them meaningful if the phrase changes:

• held: the first note.
• high: the highest note at least half an octave above the held one.
• chord: the first note with chord voices.

A phrase missing a role yields 0.0 for its features, which reads as "no evidence" rather than as a measurement.

held_centroid_std is the important one. centroid_std over the whole phrase conflates note-to-note register jumps with genuine timbral motion: a static patch played across two octaves has a large centroid_std. Restricted to the held note's span the coordinate is register-constant by construction, so it is the axis on which "a filter sweeping at 0.4 Hz" and "a static patch" are different patches at all. It needs at least 3 frames in the span, or it reports 0.0.

high_ratio = $\log$ of the high note's span RMS over the held note's. Does the patch speak in the upper register, or does its filter choke it?

chord_flatness_delta = mean flatness over the chord span minus the held span. Intermodulation and mud when voices stack.

Motion bands

held_centroid_std says how much a held note moves. It cannot say how fast. Measured on one saw-into-ladder patch under a ladder of cutoff modulations (cargo run -p auracle-features --example motion_probe --release), a 0.55 Hz sweep and a 13 Hz flutter score 0.098 and 0.094, and stepped random motion scores like a 6 Hz LFO. A linear model on those coordinates cannot hold "slow breathing, not fast wobble" — which is the first thing anyone says about a texture.

Hearing sorts fluctuation by modulation rate: a filterbank over the envelope, not just its variance (Dau, Kollmeier & Kohlrausch 1997), and the band-wise modulation power of a sound is much of what makes it recognisable as a texture at all (McDermott & Simoncelli 2011). The three coordinates are that filterbank, cut to three bands.

Over the held span, starting once the note has arrived so the attack is not read as motion — 250 ms after onset, or later if the level (smoothed over ≈ 46 ms) has not yet reached 97% of its peak — two trajectories are taken at a 256-sample hop (≈ 172 frames/s — the spectral features' own 43 frames/s would fold the fast band): brightness $c_t = \log_2(\text{centroid}_t / 20,\text{Hz})$ in octaves, and level $\ell_t = \max(\log_2 \text{RMS}_t,\ \log_2 \text{peak} - 10)$, where one unit is 6 dB — one doubling, the same currency as an octave of brightness — and a dip reads at most 60 dB deep, so one frame of digital silence in a chopped sound cannot outweigh every audible wobble. The arrival rule matters for pads: a 0.9 s swell measured from the fixed 250 ms alone read 4.3 octaves over the floor in the slow band, because a ramp is curved in log level and detrending leaves most of it. Each is linearly detrended (a ramp across the span is drift, which held_centroid_std already carries), Hann-windowed and transformed. With $r$ the detrended residual, $\sigma^2_r$ its variance and $P(f)$ its modulation power spectrum, band $B$ gets the variance share

$$v_B(r) = \sigma^2_r \cdot \frac{\sum_{f \in B} P(f)}{\sum_{f > 0} P(f)}, \qquad \texttt{motion}_B = \tfrac12 \log_2!\big(v_B(c) + v_B(\ell) + 10^{-4}\big).$$

The result is a log standard deviation in octaves. The floor, $\tfrac12\log_2 10^{-4} \approx -6.64$, is a hundredth of an octave: a static tone reads it exactly in all three bands, so "still" is one value and not numerical noise. A phrase whose held span is shorter than 0.75 s reads the floor too.

Measured on the probe ladder, the band that reads highest follows the rate: 0.55 Hz lands in slow, 2.7 Hz in mid, 13 Hz in fast, and stepped random motion spreads across slow and mid as its spectrum says it should.

What it cannot say

It does not say whether motion is regular. Separating a periodic sweep from a random walk needs several cycles in the window, and the held span holds fewer than three cycles of anything in the slow band. Both candidate measures tried — the normalized autocorrelation peak and the harmonic share of the modulation spectrum — separate periodic from random cleanly at 2.7 Hz and above, and not at all below 1.5 Hz, which is exactly where evolving textures live. A coordinate that guesses there would be taught to the model as a measurement, so regularity waits for a stimulus with a longer held span.

Deliberately compact

Eighteen dimensions is a choice. The model is a mixture of linear experts, and interpretable axes are the point: "bright", "noisy", "slow attack", "long tail" are things the DIRECTIONS tab can name and a person can recognise in their own preferences.

A 128-dimensional MFCC bank would carry more information and would be unreadable, and would make the cold start dramatically worse: every dimension is posterior variance to pay down before the model says anything at all.

Known collinearity

Measured over 1200 prior draws (cargo run -p auracle-features --example pipeline_stats --release -- 1200), the variance inflation factors are mostly comfortable, with one cluster that is not:

That is the brightness cluster — three genuine measurements of one perceptual thing. It is left standing deliberately: dropping any of them discards real signal rather than redundancy, since they disagree in informative ways (a bright noisy patch and a bright tonal patch differ in ZCR-versus-centroid). The right fix is a shared or fused prior over the cluster, which is a modelling change rather than a feature change, and is not done.

For contrast, φ_struct had two exact linear dependencies, which is a different and worse problem and was fixed by dropping columns.

φ_struct — structural descriptors

Twenty-six dimensions, free to compute.

These cost nothing: no compile, no render, just a walk of the term. That is what makes the screening cascade possible: a structure-only surrogate prunes candidates before the expensive render path. They also capture taste axes audio features cannot fully separate ("likes supersaws", "likes deep modulated chains").

The coordinates

Nineteen family counts:

n_vco  n_supersaw  n_noise  n_wavetable  n_pluck  n_formant  n_silence
n_filter  n_drive  n_time  n_mod_fx  n_reverb  n_dynamics
n_lfo  n_env  n_rand  n_follow  n_mod_shape  n_mod_logic

Seven term-level numbers:

mod_density  mod_depth_mean  amp_attack  amp_sustain  amp_release
chain_balance  frac_sidechained

Twenty-six in total, appended after the eighteen audio coordinates to give $\varphi \in \R^{44}$.

Families, not one column per module

StructFeatures keeps a raw counter per module kind internally (the Styles tab and the auto-namer both want "two filters", not "two subtractive stages"), but NAMES and to_vec collapse forty-three productions into nineteen family counts.

Two reasons.

Nothing meaningful distinguishes them. n_fold, n_distortion and n_bitcrush all answer "how much nonlinear colour". n_chorus, n_phaser, n_flanger, n_tremolo and n_vibrato all answer "how much periodic movement". A user who likes drive does not first decide which drive.

Per-kind columns arrive as near-indicator variables. The prior draws bitcrush at 2.5%, ring mod at 2% and granular at 1.5%, so those columns are zero in ~19 of every 20 pool members. A coefficient fitted on a column that is almost always zero is estimated from a handful of rows, and the Styles tab would render it beside coefficients fitted on hundreds, at the same visual weight.

Measured over 1200 draws, the extreme case: each of the four CV processors appears in under 4% of patches and each of the six combiners in under 1%. A column that is zero in 99 rows of every 100 is not a coefficient, it is a rounding error with a name in the UI.

Sixteen sparse columns would also cost sixteen dimensions of posterior variance for the cold start to pay down before the model says anything at all.

The step sequencer shows the rule applied to a newcomer. The prior draws it into about 3% of slots, so a column of its own would be exactly the near-indicator above. It joins n_rand, which has become the stepped CV family (StructFeatures::n_stepped): to a listener an S&H and a step pattern are the same gesture, a value that holds and jumps (or glides) on a clock, and they differ only in whether the values were drawn once into the genome or anew at every tick. It does not join the euclid in n_mod_logic, because a euclid emits a gate and a step sequence emits a value. The column keeps the name n_rand because stored observations carry φ names, and every row already on disk predates the step sequencer, so its n_rand already is its stepped-CV count. The panel labels the column "stepped mods".

What is deliberately not in φ

size, an exact identity

Every audio node increments exactly one raw counter, so

$$\text{size} \equiv \sum_i n_i \qquad\text{exactly, for every tree}$$

Including it makes the design matrix rank-deficient. The Gaussian prior keeps the posterior proper, so nothing crashes and no test fails, but there is an unidentified ridge along which the MH chain random-walks forever. That wrecks mixing, splits each coefficient arbitrarily between size and the counts (so the per-feature weights the Styles tab renders mean nothing individually), and poisons the taste→grammar proposal tilt, which reads exactly those coefficients.

size − depth would be no better: still an exact linear combination of coordinates already present.

The field is kept for display and naming. It just never reaches the model.

A second, subtler identity

Dropping size alone was not enough, and a VIF sweep caught it: VIF $\approx 10^9$ on every column involved, which is what an exact dependency looks like numerically.

A tree is a forest of source leaves joined by productions that each take some number of audio children, so the leaf count exceeds the total branch count by exactly one:

$$n_{\text{vco}} + n_{\text{supersaw}} + n_{\text{noise}} + n_{\text{wavetable}} + n_{\text{pluck}} + n_{\text{formant}} + n_{\text{silence}}$$ $${} - n_{\text{mix}} - n_{\text{ringmod}} - n_{\text{comp}} - n_{\text{duck}} - n_{\text{gate}} - n_{\text{vocoder}} ;=; 1$$

Silence joins that sum as a source leaf, because that is what it is: it has no children, so it ends a branch exactly as a Vco does. Joining keeps this one equation with one dropped column, and $n_{\text{mix}}$ stays the column dropped. Leaving it outside instead would make the identity exact for a tree with no holes and slack for one with them — near-exact almost always, which is a worse thing to carry than an exact dependency: an exact one is unmistakable in a VIF sweep, and a near-exact one is a large number that looks like a judgment call.

exactly, for every tree. This only became a general statement when the four dynamics productions arrived, each taking two audio subterms exactly as mix and ring mod do.

That is one equation, so exactly one column has to go, and dropping more would remove real dimensions rather than redundant ones. With both binary counts gone, $\varphi$ could not tell a crossfade from a ring modulator at all, which are about as different as two nodes in this grammar get.

So n_mix leaves: it is the one determined by the others, and its proposal tilt is recovered from the source coefficients in the engine's biased_prior. The other five stay, but never as columns of their own: ring mod lives inside n_drive, the vocoder inside n_filter, and comp/duck/gate inside n_dynamics.

Why n_dynamics is still safe

Worth checking rather than assuming, because n_dynamics is exactly $n_{\text{comp}} + n_{\text{duck}} + n_{\text{gate}}$ and it is a retained column, the only family whose members are all on the wrong side of the identity.

It is safe because the identity needs each binary count separately. n_ringmod is only ever visible summed with folds, distortions and bitcrushers; n_vocoder only summed with filters and EQs. No linear combination of the retained columns isolates either, so the equation cannot be reconstructed. n_dynamics supplies three of the six binary terms and nothing supplies the other three.

Confirmed empirically: on the 1200-draw sweep every structural coordinate came back well under 10, with n_dynamics at 1.9.

depth, a weaker but real argument

VIF $\approx 21.7$. Not exact, so the posterior stays proper, but a coefficient that unstable is not individually meaningful, and the Styles tab renders these per-feature weights as though they were. Dropped.

Health of the retained set

Every family coordinate came back under 4 on the 1200-draw sweep, the highest being mod_depth_mean at 3.8. That is the reason the families exist; forty separate module columns would not have managed it.

The three most recent additions: n_mod_shape 1.6, n_mod_logic 1.3, mod_depth_mean 3.8, with mod_density rising from 2.7 to 4.1 as the one visible cost of adding a second modulation-shape coordinate beside it.

Reproduce with:

cargo run -p auracle-features --example pipeline_stats --release -- 1200

The unit coordinates

Seven of the twenty-six are UNIT_NAMES, a subset of NAMES rather than a reordering. Each is either a normalized genome site read straight through (amp_attack, amp_sustain, amp_release, mod_depth_mean) or a ratio that is already in $[0,1]$ (mod_density, chain_balance, frac_sidechained).

The distinction matters for display: these can be rendered as percentages honestly, whereas a family count cannot.

amp_sustain is also the coordinate the 1e30 sentinel killed; see the sentinel.

Standardization

A Gaussian prior over $\theta$ only makes sense on a common scale. The fitting of that scale is a view of the data, not the data.

Raw $\varphi$ scales vary wildly: counts 0–5, log-octave axes ~0–1, log crest 0–4. The standardizer is a per-dimension affine map

$$z_j = \frac{\varphi_j - \mu_j}{s_j}$$

re-fit at every posterior fit, over the union of the observation log and the live pool.

It persists with the profile, always

$\theta$ is only meaningful relative to the standardization that produced it, so a taste profile carries both or neither. A log without its standardizer is a set of numbers whose units have been lost.

The log stores raw $\varphi$, which is what makes re-fitting safe: a re-fit standardizer simply re-expresses the same evidence on a scale that still matches where the pool actually is. Had the log stored z-scores, the scale would be frozen at whatever the pool looked like on the day each vote was cast.

The inverse map exists for exactly one reason: migrating logs written before raw-φ logging. A legacy log plus the standardizer it was written under is the raw data, just encoded.

Robustness: a fault detector, not a policy

Standardizer::fit is the plain moments unless a column is provably runaway. On clean data it is bit-identical to the naive fit.

Per column:

1. Drop non-finite cells (a column that is entirely non-finite falls back to $\mu = 0, s = 1$, the reading of "no usable evidence on this axis").
2. Compute the plain moments $(\mu, s)$.
3. Compute winsorized moments $(\mu_w, s_w)$ with the extreme 2% of each tail pulled in.
4. Use the winsorized pair only if $s > 10^6 , s_w$.

const WINSOR_TAIL: f64 = 0.02;
const WINSOR_MIN_ROWS: usize = 10;
const RUNAWAY_RATIO: f64 = 1e6;

Finally $s_j \gets 1.0$ if $s_j < 10^{-9}$, so a degenerate column standardizes everything to itself rather than dividing by nothing.

Why not just winsorize always

Because it was tried first and thrown out, and the measurement is why.

Clipping 2% of each tail unconditionally took a 16-seed search_health --climb run from +1.877 ± 0.362 mean gain, climbing on 15 of 16 seeds, to +0.204 ± 1.347 on 11 of 16 — with one seed at −18.2.

Trimming a real tail is not free. A data-hygiene fix that costs the search a standard deviation is not a fix. So the clip became a fault detector: plain moments unless the column is provably broken.

Why the threshold is $10^6$

The first guess was 8×, on the reasoning that clean columns differ "by a factor of order one". The paired run said otherwise: 15 of 16 seeds came back bit-identical and the sixteenth went from +0.12 to −40.5.

So the threshold was measured.

cargo run -p auracle-features --example winsor_ratio --release -- 150

fits 150 clean 48-patch pools and reports the largest plain/winsorized $\sigma$ ratio per column. Over 6 000 column-fits the maximum is 14.6 (rms_std:p2), with chord_flatness_delta:p2 at 13.9 — and still climbing with the sample, because a log-scale audio descriptor over a pool that happens to contain one near-silent patch genuinely has a tail.

Meanwhile a single $10^{30}$ in a column whose real values live in $[0,1]$ gives a ratio near $2 \times 10^{29}$.

$10^6$ sits five orders above anything clean $\varphi$ has been observed to produce and twenty-three below the fault, which is about as far from both edges as this quantity allows.

The tail size

$$k(n) = \begin{cases} 0 & n < 10 \ \mathrm{clamp}\big(\lceil 0.02n \rceil,\ 1,\ \lfloor (n-1)/2 \rfloor\big) & n \ge 10 \end{cases}$$

ceil, not floor. The first version used floor and was inert exactly where it was needed. The reference population is a 48-patch pool, and $\lfloor 48 \times 0.02 \rfloor = 0$, so nothing was clipped at the size the app actually fits at. The pre/post measurement came back bit-identical and said so.

Below 10 rows nothing is winsorized at all: with a handful of values the min and max are the spread, and pulling them in throws away the only information about it.

There is also a hi > lo guard, which keeps a legitimately rare column intact: when 96% of rows are the same value (a module that appears in two patches out of forty-eight) the tail is the column's only information, and clipping it would flatten a real coordinate to nothing in the name of robustness.

Winsorizing rather than trimming

When it does fire, the extreme rows are pulled in, not dropped. The rows are not independent draws from a nuisance distribution: they are the patches the player actually met, and a real extreme patch is evidence about where the pool is. Winsorizing keeps its vote and takes away only its leverage on the units.

Two properties, both tested

A single escaped row cannot kill a column. Fifty values spread over $[0,1]$ plus one $10^{30}$: unwinsorized, the outlier owns the mean and the scale, every real patch standardizes to the same place, and the column is dead. The model can never learn from an axis whose fifty honest values are separated by $10^{-30}$ of a standard deviation. The test asserts $\sigma$ moves by less than 0.05 and that the coordinate still separates two real patches by more than 3.

Clean columns come out bit-identical to the plain moments. The load-bearing property, asserted with assert_eq! on floats, because "close enough" would let the regression back in, over a heavy right tail, a near-constant column, a bipolar one, a count with a legitimately extreme member, and a five-row column below the floor entirely.

One implementation detail exists to protect that property: the column stays in row order and the quantiles come off a copy. Floating-point addition is not associative, so summing the sorted column would move the mean by a ULP on clean data, and the whole claim is that clean data comes out bit-identical.

Where this fits in the defence

The fault this detector exists for is fixed upstream of here: clamp_domains on load, FeaturizeError::OutOfDomain before the render, the load-time repair. This is the line that means the next escape costs a coordinate's precision rather than the coordinate.

Layers above should make this unnecessary. It exists anyway, because in the sentinel incident the value got through everything that was supposed to stop it.

Utility as a max of experts

A candidate is as good as its best lens thinks it is. Two more obvious designs cannot represent a cross-island comparison at all.

The form

$$u(x) = \max_{k \in 1..K} ; \theta_k^\top z(x), \qquad z(x) = \frac{\varphi(x) - \mu}{s}$$

$K$ style lenses, each a linear functional on the standardized feature vector. Utility is the maximum, not a weighted mixture.

At $K = 1$ this reduces exactly to Bayesian linear regression on $z$, which is a useful property: the mixture is a strict generalization with no special-casing at the boundary.

pub fn utility_mix(&self, phi: &[f64]) -> f64 {
    self.theta.iter()
        .map(|t| dot(t, phi))
        .fold(f64::NEG_INFINITY, f64::max)
}

Why a maximum

Taste is multi-modal. One person can love dark drones and bright plucks ("ambient-me" and "acid-me"), and those are not points on one axis. A single linear utility would average them into a preference for neither, and would then be confidently wrong about both.

The max form gives each island its own lens, and every judgement, including a duel across two islands, compares candidates on the shared scale $u = \max_k u_k$. A dark drone and a bright pluck are both scored, each by whichever lens likes it most, and the comparison is well-formed.

Two rejected designs, and why

A per-session style latent $z_s$

"One mood per session — sample which lens is active, then use it."

Fails because it cannot represent several islands inside a session. A user who auditions a pad, then a bass, then a pad in one sitting is not switching moods; they have two preferences at once. Whenever the session's latent is wrong for the current candidate, every observation in that session is scored by the wrong lens.

A per-observation marginalized lens

"Marginalize over which lens judges each observation."

Fails on a sharper point: it forces both duel items through the same lens, so a cross-island comparison is unrepresentable. There is no lens under which "the drone beats the pluck" is a sensible statement if the drone lives in lens 1 and the pluck in lens 2, and a duel between them is exactly the question the acquisition rule will ask.

This is not a theoretical objection. A synthetic bimodal user exposed it: the marginalized mixture failed to beat $K = 1$. Adding capacity made the model no better, which is the signature of capacity the likelihood cannot use.

What max-utility buys structurally

There are no discrete latent sites at all. No lens assignment to sample, no categorical variables, no label-switching during inference to fight. Every site in the model is an f64, which means fugue's generic adaptive single-site MH applies unchanged — no custom kernel, no Rao-Blackwellization.

Label permutation is resolved post hoc instead, by TastePosterior::aligned.

$K$ is an upper bound, not a claim

$K = 5$ by default (SessionConfig::k_styles), and the fitted number of live lenses grows with evidence.

Nothing enforces that; it falls out. A lens with no evidence to explain stays near its prior, and style_share reports what fraction of the pool each lens actually claims as its best. A lens claiming ≈0% is idle: the user's taste has fewer islands than $K$, and the app dims it rather than inventing a name for it.

So $K$ is capacity, and the data decides how much gets used.

The prior, and the correction $K$ forces

$$\theta_{k,j} \sim \mathcal{N}(0, \sigma_\theta^2), \qquad \sigma_\theta = \frac{1}{\sqrt{d}; s_K}$$

The $1/\sqrt{d}$ factor is standard: with $\lVert z \rVert^2 \approx d$ for a standardized vector, it makes the prior utility of a candidate roughly unit-variance, so likelihood scales stay sane at any feature count.

The $s_K$ factor is the correction the max form forces, and it is easy to miss.

Under the prior each $u_k$ is marginally $\mathcal{N}(0,1)$, so $u = \max_k u_k$ is the maximum of $K$ iid standard normals — whose standard deviation falls with $K$:

The mean shift cancels in duels (both sides shift equally) and is absorbed by $\tau$ and the cutpoints elsewhere. The variance shrinkage does not cancel. Left uncorrected, $\mathrm{Var}(u_a - u_b)$ drops from 2.0 at $K=1$ to 0.90 at $K=5$ — so growing $K$ mid-session would quietly make the model less able to express a strong preference.

That is the opposite of what adding capacity should do, and it would present as "the model gets vaguer the longer I use it".

Dividing by $s_K$ restores invariance: $\mathrm{Var}(u_a - u_b)$ is the same at every $K$.

What the interface reads off this

responsibilities is a posterior distribution over which lens applies, which is strictly more informative than an argmax and is what lets a candidate sit visibly between two islands.

One utility, three likelihoods

Every feedback mode conditions the same latent $u$. They differ only in how an answer connects to it.

All three enter as a single factor carrying the total weighted log-likelihood, so from fugue's point of view the model has one observation node regardless of how many kinds of feedback the log contains.

Pairwise duels — Bradley–Terry

$$P(A \succ B) = \sigma\big(u(A) - u(B)\big)$$

Feedback::Duel { a, b, chose_a } => {
    let d = s.utility_mix(a) - s.utility_mix(b);
    log_sigmoid(if *chose_a { d } else { -d })
}

The primary signal: best statistical properties, lowest cognitive load. It identifies $u$ up to an additive constant, which is exactly the right amount of information: a preference relation does not have an origin, and pretending otherwise is what makes absolute ratings drift.

Note that $u$ here is the mixture utility, so a duel across two islands is a comparison of "the drone's best lens's opinion" against "the pluck's best lens's opinion". That this is well-formed is the whole reason for the max form.

log_sigmoid is computed stably as $-\mathrm{softplus}(-v)$ with $\mathrm{softplus}(t) = \max(t,0) + \log(1 + e^{-|t|})$. The naive $\log(1/(1+e^{-v}))$ underflows for moderately confident predictions, which is exactly where a fitted model spends its time.

Keep / kill — a thresholded Bernoulli

$$P(\text{keep}) = \sigma\big(u(x) - \tau_s\big), \qquad \tau_s \sim \mathcal{N}(0,1)$$

$\tau_s$ is a per-session latent, one per session in the log.

The app emits one side of it: a bank row's cut calls record_keep(id, false) once its 7 s undo window closes (main.js, cutRow). Nothing emits a keep; the triage surfaces that would are unbuilt.

"Feeling picky today" is therefore modelled rather than treated as noise. A session where you kill almost everything is read as a strict session (a high $\tau_s$) rather than a transformation of your taste. Without the per-session threshold, a strict day and a generous day would average into a meaningless global bar, and both days' data would be degraded by the other's.

One implementation subtlety: reweighting an old observation against a posterior fitted before that session existed finds no $\tau_s$ site, and contributes zero rather than guessing. No threshold site means no threshold evidence.

Star ratings — a cumulative logit

$$P(y = k) = \sigma(c_k - u) - \sigma(c_{k-1} - u)$$

with 0-based cutpoints, $c_{-1} = -\infty$ (so the first term is 0) and $c_{K_{\text{cat}}-1} = +\infty$ (so the last is 1). Six categories by default, hence five cutpoints.

let upper = if k == n_cats - 1 { 1.0 } else { sigmoid(s.cuts[k] - u) };
let lower = if k == 0          { 0.0 } else { sigmoid(s.cuts[k - 1] - u) };
(upper - lower).max(1e-12).ln()

This treats ★★★ as "between two cutpoints" rather than as the number 3, which is the point. A rating is an ordinal judgement, and modelling it as a real number asserts that the gap between 1 and 2 stars equals the gap between 4 and 5, which no rater believes.

Because the cutpoints are fitted, the model absorbs scale drift: a user who becomes harsher moves the cutpoints, not $\theta$. Without that, a change in rating habit would be indistinguishable from a change in taste.

Enforcing the ordering

Cutpoints must be increasing. Rather than constrain the sampler, the model samples unconstrained normals and transforms:

$$c_0 = -2 + 1.5,r_0, \qquad c_j = c_{j-1} + \exp(-0.5 + 0.7,r_j), \quad r_j \sim \mathcal{N}(0,1)$$

The exponential increments are positive by construction, so ordering holds for every draw. No rejection, no constrained kernel, and the generic single-site MH applies unchanged.

The constants place the prior sensibly: $c_0$ near $-2$ (so a 0-star rating means "well below average"), and increments with a median of $e^{-0.5} \approx 0.61$ so the five cutpoints span a few units of utility.

Edit-beats-original

Not a fourth likelihood, but a duel with a provenance tag. Committing a hand edit with my edit is better records Duel { a: edited, b: original, chose_a: true }.

The tag is what makes the claim auditable. Provenance distinguishes:

These make the same claim in the log, and there is no reason to believe they are equally reliable. Calibration scores them separately, which is the only way to find out rather than assume.

Recency weighting

Every observation's log-likelihood is scaled before summing:

$$w_i = 0.5^{,(n - 1 - i)/h}, \qquad h = 150$$

so the newest observation has weight 1 and one $h$ back has weight $\tfrac12$. Default recency_half_life = Some(150.0); None disables forgetting entirely.

$$\log p(\mathcal{D} \mid \theta) = \sum_i w_i , \log p(y_i \mid \theta)$$

Taste is allowed to change, and a model weighting a vote from three sessions ago equally with one from a minute ago would fight the user when it did. The cost is stated plainly: this is not a proper Bayesian posterior over a stationary parameter, it is a tempered/discounted likelihood, chosen because stationarity is the wrong assumption about a person.

Implicit signals are out of scope

Listen time, replays, exports, hover duration: not recorded.

They are cheap to collect and easy to misread: a long listen can mean fascination or confusion, and the two have opposite signs. This version prefers less data that means what it says.

Site count, and what it costs

The model has

$$K \cdot d + S + (n_{\text{stars}} - 1)$$

sample sites. With $d = 44$ and 6 star categories, that is $44K + S + 5$: **49

• $S$** at $K=1$ and 225 + $S$ at $K=5$.

Single-site MH re-executes the whole program on every step, so every site is reconstructed once per step. Two consequences, both measured by auracle-taste/examples/fit_bench.rs:

• The fit is several times slower at the $K$ cap than at the first fit.
• The step budget is fixed, so a mature fit gets proportionally fewer sweeps per site than an early one. Growing $K$ makes the fit both slower and statistically thinner.

That is a real tension in the design, and it is why the address table is hoisted out of the step loop. Building addresses inline cost a format!, a re-allocation and a SipHash per site per step, which measured as the bulk of a mature fit's wall time.

The posterior

MCMC when it can afford to, importance sampling when it cannot, and an honest signal for when the cheap path has run out.

The full fit

TasteModel::fit runs fugue's adaptive single-site Metropolis–Hastings:

Every site is an f64 — there are no discrete latents — so the generic chain applies with no custom kernel. Adaptation tunes per-site proposal scales during warmup.

Each MH step moves one site, so a useful way to budget is $\text{steps} \approx \text{sites} \times \text{desired effective sweeps}$. At $K=5$, $210 + S$ sites over 10 000 steps is roughly 48 sweeps per site — which is thin, and is the tension noted in site count.

The result is uniformly weighted:

TastePosterior { cfg, samples, weights: vec![1.0 / n; n] }

The address table

SiteAddrs::new builds every site address once per fit, and the model clones Address (an Arc refcount bump plus a cached hash) into each node.

Building addresses inline (addr!(format!("theta{k}"), i)) cost a format! into a String, a re-allocation into Arc<str> and a SipHash of that string, per site per step: roughly 3.7 M allocations per mature fit, and measurably the bulk of the fit's wall time (examples/fit_bench.rs; the fit is steps × sites-shaped and the likelihood is only ~20% of it even at 100 observations).

The addresses are a pure function of $(K, d, n_{\text{stars}}, S)$, none of which move during a fit. And they are produced by the same addr! invocations as before, so traces, serialized posteriors and warm-start paths see byte-identical addresses.

Thinning happens at the driver, not after it

97% of the chain is discarded, and it is discarded as it is produced.

That used to happen one line after the whole chain was built. adaptive_mcmc_chain materialized every step — pushing (TasteSample, Trace) per iteration into a Vec it returned by value — and only then did step_by(stride) keep every 20th. At $K = 5$ that is ~10 000 Trace clones of 225 + S BTreeMap entries each, held live at once to retain 500: 303.1 MB peak RSS at the shipped budget, scaling with n_samples, and a plausible mobile-Safari OOM on a 32-bit heap rather than mere waste.

It could not be fixed here. The retention was inside fugue's chain driver, and the pieces needed to reimplement that driver with identical RNG consumption (single_site_mh_step, propose_and_score, SingleSiteProposalHandler) are private or pub(crate); forking fugue's inference core into this crate would have traded a memory spike for a correctness hazard on every upgrade.

So it was fixed upstream instead, as fugue-ppl 0.2.2: adaptive_mcmc_chain_thinned takes a stride and pushes only when i % thin == 0.

16.7× less peak memory for bit-identical draws — the unchanged checksum is the point of that table rather than a footnote to it. thin gates the push and nothing else: every transition still runs, so the RNG is consumed in the same order and quantity, and $0, \text{stride}, 2\cdot\text{stride}, \dots$ is exactly what step_by kept. fit_bench's per-fit checksum is the Auracle-side witness; fugue's thinning_retains_exactly_the_draws_step_by_would is the upstream one.

What stays resident is the 500 draws the posterior actually keeps, so the peak no longer scales with mcmc_samples at all — the budget is now free to be chosen on the recovery tables rather than against a memory ceiling.

Between fits: sequential importance sampling

A full fit costs seconds and cannot run after every vote. So each new observation is folded into the existing draws by reweighting:

$$w_s ;\leftarrow; \frac{w_s , p(y \mid \theta_s)}{\sum_{s'} w_{s'} , p(y \mid \theta_{s'})}$$

let m = ll.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
let mut w: Vec<f64> = (0..n).map(|i| self.weight(i) * (ll[i] - m).exp()).collect();

This is exact (the weighted draws target the updated posterior) and it costs $O(S)$. It is what makes each duel respond to the one before it; without it the acquisition rule reads a frozen posterior and re-asks the same question until the next full fit.

The max-shift before exponentiating is the usual guard. Log-likelihoods here are bounded above by 0, so it is not strictly needed for duels, but it keeps mixed modalities safe.

Effective sample size

$$\mathrm{ESS} = \frac{1}{\sum_s w_s^2}$$

Equals the draw count for uniform weights, and collapses toward 1 as weights concentrate.

Importance weights degenerate, and ESS says so rather than letting the posterior quietly become one point wearing 500 hats. It is the trigger for paying for a real refit.

Systematic resampling

When weights have concentrated far enough, resampled() draws the weighted set back to a uniformly weighted one of the same size.

The trade: resampling produces duplicate draws, so the sample is impoverished but still spans the posterior's support, and ESS on the fresh uniform weights no longer claims more information than is there. Left unresampled, almost all the mass sits on one draw, and a "posterior" of one point tells the acquisition function it is certain when it is merely exhausted.

It is a stopgap between full refits, not a substitute for one.

Deterministic (systematic, offset $\tfrac{1}{2N}$) rather than multinomial, because every other stochastic step in the engine is seeded and reproducible and this one has no reason not to be.

The refit trigger

pub fn needs_refit(&self) -> bool {
    match &self.posterior {
        Some(_) => self.resamples_since_fit > 0,
        None => !self.log.is_empty(),
    }
}

So the condition is not "every $n$ duels": it is "we have had to resample at least once since the last real fit", i.e. the cheap path has provably run out of road. The app surfaces this as the teaching meter and the wordmark's listening lamp; a refit happens at most every six duels, and only when this says so.

Label alignment

Mixture posteriors are permutation-symmetric in the style labels (label switching), so per-style summaries are meaningless on a raw posterior.

aligned() resolves it post hoc, in two passes:

1. Relabel every sample to best match a reference (the last sample), maximizing total $\theta$ cosine similarity across lenses.
2. Recompute the mean of the pass-1 result and relabel against that.

Alignment is exhaustive over permutations, which is fine because $K \le 5$ and $5! = 120$. No-op at $K = 1$.

Call it before theta_mean, theta_std, style_share or anything else per-style. Aggregate quantities (utility_mix, prob_prefers) are permutation-invariant and do not need it.

What the summaries are

All weighted by the importance weights:

prob_prefers marginalizes $\theta$ and the weights and the per-candidate lens choice, which is why it is the right thing to show on a bank row: it is a predictive probability, not a point estimate's opinion.

Serialization

TastePosterior serializes to JSON, and weights carries #[serde(default)] so older persisted posteriors, written before reweighting existed, deserialize to empty and are read as uniform.

The observation log remains the source of truth. A posterior snapshot is a cache: it can always be recomputed from the log plus its standardizer, and that is exactly what a profile stores.

Calibration

Every duel is forecast before it is answered. This page is how those forecasts are scored, and why the obvious metric would have lied.

Prequential by construction

record_duel scores the posterior's $P(A \text{ wins})$ and only then appends the observation. So every forecast is an out-of-sample, one-step-ahead prediction: the model has never seen the answer it is being scored on.

Why not accuracy

A running count of $p > 0.5$ outcomes is accuracy, and accuracy is not a proper scoring rule. Two failures, and the second is fatal here:

It cannot see sharpness. A model that says 0.51 every time and is right 51% of the time scores identically to one that says 0.99 and is right 51% of the time. The second is wildly overconfident and accuracy cannot tell you.

It is pinned near 50% by the acquisition rule. An information-seeking rule deliberately picks pairs near $p = 0.5$, because those are the questions worth asking. So the hit rate sits near chance by construction: a perfectly calibrated model looks like a coin flip, and the user concludes it is not learning.

The second point is what makes accuracy harmful rather than merely crude: it penalizes the search for doing its job.

hit_rate is still computed and shown, only so the interface can display how misleading it is next to the real number.

Brier score and skill

$$B = \frac{1}{n}\sum_{i} \big(p_i^{\text{chosen}} - 1\big)^2$$

where $p^{\text{chosen}}$ is the probability the model gave to the option the user actually picked. Lower is better; $B = 0.25$ is what always saying 0.5 scores.

Reported as skill against that baseline:

$$\text{skill} = 1 - \frac{B}{0.25}$$

Brier is proper and bounded, and it moves as sharpness improves rather than only as accuracy does, which is the property accuracy lacked.

Log-loss, and what it may not be compared across

$$\text{LL} = \frac{1}{n}\sum_i -\log p_i^{\text{chosen}} \quad \text{(nats)}$$

Baseline $\log 2 \approx 0.693$.

Comparable across time for one acquisition rule. Not comparable across acquisition rules: an information-seeking rule serves duels near $p = 0.5$, which carry the highest log-loss by construction. Comparing two rules on their own self-chosen question sets would score the willingness to ask hard questions as a failure.

check_log_loss is the version for that comparison. See below.

The selection-bias fix

The acquisition function chooses which duels get scored, which means overall skill is measured on a question set the model helped select. That is circular.

So a fraction of duels are drawn uniformly at random and flagged Forecast::random_check. The app marks them ◇ unbiased probe, and calibration restricted to those is unbiased:

It costs a small share of the query budget and it is the only number here that means what it says unqualified.

The reliability diagram

Five buckets over $P(A \text{ wins})$ (N_BINS = 5, the most a small session can fill without every bucket being noise). Each bucket reports:

Plotted, the diagonal is the claim and the dots are the reality. This is the display that makes calibration legible: a single number cannot distinguish "overconfident at the top end" from "underconfident in the middle", and the shape of the failure is what tells you what to do about it.

The app draws a whisker per bucket for how much a bucket that size could wobble by chance, so a dot off the diagonal with a whisker crossing it is not yet evidence of anything.

By provenance

The same scores, split by how the answer was collected:

pub struct ProvenanceScore {
    pub provenance: String,  // "duel" | "heard_edit" | "self_report" | "perform_offer"
    pub n: usize,
    pub brier: f64,
    pub log_loss: f64,
    pub skill: f64,
}

The comparison this exists for: a hand edit committed through a heard duel and one committed by ticking my edit is better make the same claim in the log, and there is no reason to believe they are equally reliable. Scoring them against forecasts the model made before either answer arrived is the only way to find out which, and it costs one tag.

Empty streams are omitted, so a session that has never committed a hand edit carries exactly one row.

Interpreting it

The user-facing version of this table is in Reading what it learned.

Why the number can look bad

Committing to a forecast before each answer and then reporting the error against a proper scoring rule means the model can publicly fail, and early on it does.

That is what makes the number worth reading later, and it is why the app shows "not beating a coin flip yet" rather than hiding the metric until it flatters.

The Boltzmann target

One distribution, two factors: the grammar supplies parsimony, the learned taste supplies direction, and $\beta$ is the single dial between them.

The target

$$\pi_\beta(x) ;\propto; p_{\text{grammar}}(x);\exp!\big(\beta \cdot \E[u_\theta(\varphi(x))]\big)$$

This is fugue-evo's EvolutionModel with the learned utility plugged in as fitness, so the whole thing becomes an ordinary probabilistic program and typed-MH / SMC drivers apply unchanged.

What each factor does

$p_{\text{grammar}}(x)$ is the parsimony pressure. It is the prior probability of the term under the typed PCFG, not a penalty term. Deeper terms pay more prior mass by construction, because each extra level multiplies in another Bernoulli that came out "processor" plus that node's own parameter draws.

Ad-hoc size penalties in genetic programming need tuning, interact badly with fitness scaling, and leave the target distribution unwritten. Here the target is written down, and the parsimony term is a probability rather than a hyperparameter.

$\exp(\beta \E[u_\theta])$ is the direction. The expectation is over the posterior, so the search climbs the model's mean belief and is not seduced by a single confident-looking draw.

$\beta$

SessionConfig::beta, default 2.0.

One dial for conservatism, which is the practical payoff of writing the target down: there is no explore/exploit schedule to tune, no diversity term, no niching parameter. Tempering the same target is also how tempered SMC would work if it were wired up.

Fitness through the surrogate

SurrogateFitness is the bridge:

impl Fitness for SurrogateFitness {
    fn evaluate(&self, genome: &PatchTree) -> f64 {
        match featurize_memo(genome, &self.phrase, &self.memo, false) {
            Ok((cf, _)) => {
                let phi = self.standardizer.transform(&cf.features.phi());
                self.posterior.utility_mix(&phi).0
            }
            Err(_) => QUARANTINE_FITNESS,
        }
    }
}

Three things in nine lines:

Quarantine is a fitness, not just a filter. QUARANTINE_FITNESS = -50.0, so a pathological candidate contributes a large negative factor to the target and the search learns to avoid the region rather than repeatedly sampling it. That is safety layer 2; hiding alone would leave the search wasting budget somewhere it cannot see is bad.

The standardizer must be the one the observations were made under. $\theta$ is meaningless against any other scaling; see Standardization.

want_audio: false. The surrogate only ever wants $\varphi$; nothing in a refinement generation is played. Asking for samples would undo the memo: a miss would convert 141k f64s it then drops, and a hit would copy a ~565 KB buffer out of the audio tier. Twice per MH step, ~96 times per seed, that is tens of megabytes of churn for a value discarded on the next line.

Why the render memo matters

It is what makes the walk affordable at all.

adaptive_single_site_mh executes the model twice per step: once to re-score the current trace (bit-identically the tree the previous step accepted, and therefore already featurized) and once for the proposal. Without a memo, one render in two is a recomputation of a number the walk already has.

At ~600 ms per render, a 40-step walk from each of 10 seeds is 800 renders without the memo and 400 with it. That is the difference between a generation taking half a minute and taking a minute, per generation, forever.

What is not sampled from this

What ships is not a sample from $\pi_\beta$. Refinement runs a short adaptive single-site MH walk warm-started from each of the best pool members and keeps the final state: local hill-climbing on that target, which is what a candidate pool needs, rather than a draw from it.

Tempered SMC with the crossover population kernel remains the design. The distinction is in Refinement.

Proposals, and the taste tilt

The loop closes here: what the model learns reshapes the grammar the search walks — what it proposes, and, because the tilted grammar is installed as the prior, what it scores against too.

Moves

Refinement uses fugue's adaptive single-site MH over the trace, so the move set is whatever the trace machinery provides:

• Parameter moves perturb one continuous or discrete site.
• Structural moves regenerate a subtree, which changes the set of sites and is therefore a reversible-jump move. fugue handles the Jacobian bookkeeping; Auracle does not implement it.

The structural moves are the same lattice as hand edits. One vocabulary, two callers.

The tilt

Once a posterior exists, the grammar's categorical weights are reshaped by what it has learned:

$$w'_i ;\propto; w_i \cdot \mathrm{clamp}!\big(e^{\eta t_i},\ \tfrac14,\ 4\big)$$

then renormalized. SessionConfig::proposal_tilt is $\eta$, default 0.6.

pub fn tilt_weights(base: &[f64], tilts: &[f64], eta: f64) -> Vec<f64> {
    let mut out: Vec<f64> = base.iter().zip(tilts)
        .map(|(w, t)| w * (eta * t).exp().clamp(0.25, 4.0))
        .collect();
    let sum: f64 = out.iter().sum();
    if sum > 0.0 { for w in &mut out { *w /= sum; } }
    out
}

The function is pure, which is why the taste→grammar mapping is testable without an MCMC fit. That matters for a mapping this easy to get subtly wrong.

The clamp

$[\tfrac14, 4]$ bounds every multiplier, so no module kind is ever starved or monopolized.

Without it a confidently-fitted coefficient could drive a kind's proposal weight to effectively zero, and the search would stop being able to discover that it was wrong about that kind. A prior that has been argued out of considering an option cannot be argued back in by evidence it can no longer generate.

Where $t_i$ comes from

biased_prior builds the tilt vector from the posterior, in three steps.

1. Blend the lenses by their pool share.

$$\bar\theta = \sum_k \text{share}_k , \theta_k^{\text{mean}}, \qquad \bar\sigma = \sum_k \text{share}_k , \theta_k^{\text{sd}}$$

Share-weighted rather than uniform, so an idle lens (one claiming ≈0% of the pool) contributes ≈nothing to how the search proposes. Uniform weighting would let a lens with no evidence steer the search as hard as one with plenty.

2. Shrink each coefficient by its own uncertainty.

$$\mathrm{shrink}(\theta, \sigma) = \theta \cdot \frac{|\theta|}{|\theta| + \sigma}$$

Same shape as a signal-to-noise weighting, and chosen over a hard significance cut for a specifically musical reason: a cut makes the proposal distribution jump discontinuously as evidence accumulates, and users hear that as the instrument changing its mind. A smooth ramp is a model getting more opinionated; a threshold crossing is a different instrument arriving mid-session.

3. Map coordinates to categorical slots. The source-kind tilts read n_vco, n_supersaw, n_noise, n_wavetable, n_pluck, n_formant directly; processor and modulation tilts read their family coordinates.

The n_mix reconstruction

n_mix is not a column of $\varphi$: it was dropped to break an exact linear dependency.

But the search still needs some tilt for the mix production, and biased_prior recovers it from the source coefficients. That is legitimate precisely because of the identity that forced the drop: n_mix is determined by the other counts, so information about it is present in what remains. The dependency that made the column unusable as a regressor is what makes it recoverable as a tilt.

Why tilt rather than only score

A scored-only search is limited by what it happens to generate. If the prior draws bitcrush into 2.5% of terms, then no matter how much the model likes bitcrush, only 2.5% of proposals will contain one and the search has to wait for luck.

Tilting the grammar means the search looks where the model expects to find things. Combined with the clamp, it is a change of emphasis rather than a change of support: every kind stays reachable, and the ones the model believes in get proposed more often.

Structural taste, specifically

Note that the tilt reads the structural coefficients. That is a deliberate asymmetry: $\varphi_{\text{struct}}$ coordinates map onto grammar productions more or less directly (n_filter ↔ the filter production), whereas an audio coefficient like centroid_mean has no single production to point at. Brightness is a property of the composition, not of a module.

So the audio half of $\theta$ influences the search only through the fitness factor, and the structural half through both the fitness factor and the tilted prior. Turning centroid_mean into a proposal tilt would require a model of which productions raise brightness, which is a model nobody has fitted.

Locks as conditional refinement

Locking is exact rather than heuristic: Metropolis-within-Gibbs on the conditional posterior. The argument depends on one detail that is easy to omit.

The claim

Let $\mathcal{L}$ be a set of trace addresses. Refinement with $\mathcal{L}$ locked samples from

$$\pi_\beta\big(x_{\neg\mathcal{L}} ;\big|; x_{\mathcal{L}}\big)$$

That is the target distribution conditioned on the locked sites holding their current values. Not "mostly avoids changing them"; conditioned on them.

That is exactly Metropolis-within-Gibbs: a valid MCMC scheme in which a subset of coordinates is held fixed and the remainder is updated by MH steps that respect the constraint.

The implementation

pub fn violates_locks(prev: &Trace, next: &Trace, locked: &HashSet<String>) -> bool

A proposal $x \to x'$ is rejected if it changes, deletes, or creates any address in $\mathcal{L}$. Rejection happens outside the kernel: the move is simply not taken.

Why all three, and why both directions

The third, creates, is the one that gets omitted, and omitting it breaks the proof.

Scanning only prev catches changes and deletions. But a birth at a locked address would be allowed through, while the death that would undo it is rejected. The constraint region is then asymmetric:

$$x \to x' \text{ allowed}, \qquad x' \to x \text{ rejected}$$