product-vamp/docs/composer/evaluation_contract.md

# Canonical phrase evaluation and shared learning

`Selector.complete(actions, home, start, end)` is authoritative. It concatenates
selected sounding events, merges only explicit ties, reconstructs silence, and
calls the versioned `phrase-selection-2` evaluator. Its exact rational total is
the sum of its reported contributions. Constructor labels earn no reward.
The same sounded music and home identity have the same complete evaluation
regardless of action partitioning. Repeated attacks remain different from ties.

The record exposes raw normalized values, weights, contributions, total, span and
attack count. Common-time frontiers score only the heard portion; the remaining
route is preserved in search state. Pending future treatment features are not a
claim that a resolution has already sounded. Completed alternatives cover the
same allocation. Retrieval costs are explicitly heuristics, not published
whole-phrase scores. Expensive validation runs before a retained successor may
advance; rejected proposals are replaced from their endpoint bucket.

General priors concern large leaps, a soft register corridor, oscillation,
repeated attacks, interruption, ordered source relationships, realized-theme
recurrence, sustained chord-tone arrival, and directed motion. Learned features
may describe duration, relative metrical placement, chord quality/relative pitch,
relative motion, register band, source rhythm, theme recurrence, silence context,
and bounded pending obligations. Silence has no fabricated register. Missing
harmony covers only the actual unharmonized interval, not the rest of a phrase.

## Development learning

`audition.fit_selection fit` uses completed ordinary source-only rollouts.
`audition.structured_learning` adds shared within-role ranking inequalities and
uses pinned development-only `z3-solver==4.13.3.0`. Coefficients are integers within
±1024. Objectives minimize nonzero coefficients then total absolute magnitude;
solver work uses a deterministic resource budget. Exhaustion returns no model.
An unsatisfiable core means incompatibility within this schema/bound, not a proof
that no generic musical model could reproduce the examples.

`audition.train_completed --previous-round` retains prior complete-output
constraints. It verifies source/example hashes, role, evaluator, semantic
algorithm, fixed priors and production data with learned weights excluded.
Only changing weights or their provenance permits reuse; changing the underlying
musical conditions requires a new, explicitly identified training experiment.
Duplicate inequalities are removed. No previous generated part becomes a
production input: these are development-only learning records.

Before combinatorial optimization, the fitter checks exact integer intervals for
zero or one nonzero coefficient per independent role. If all roles admit these,
enumerating every allowed feature proves the minimum support and its minimum L1
solution directly. This repaired a measured solver-budget exhaustion on a small
feasible problem; it changes the solver strategy, not the acceptance gate.
The post-fit first-successor diagnostic can disprove full reproduction when no
compatible opening survives. Surviving that check cannot prove reproduction.
Compatibility requires the complete committed attack duration. A clipped match
to the first portion of a target hold does not count as surviving reproduction.

Only demonstrated identical-feature conflicts may request a new conjunction of
two or three whitelisted conditions. Conditions are chord quality, root-relative
degree, relative motion, metrical category, duration, and ordered source evidence.
No source ID, title, path, hash, absolute measure, target sequence, arbitrary
predicate, or per-song branch is admitted. Constructor-family weights are rejected.
Conjunction semantics have independent positive, negative and transposition tests.
Any actually induced rule is recorded as training-dependent; no untested learned
rule or solver result is promoted automatically.

The training examples may affect coefficients and induced rules. That is an
explicit training dependency. Production target-file absence does not prove
independence of learned knowledge from those examples. Runtime composition uses
plain validated coefficient data, not Z3, target paths or a phrase-retrieval bank.

The previous prefix fitter is retired. Target-constrained derivation remains only
a stateful coverage probe, never a generated winner. A completed training iteration
is not the release gate: separate cold ordinary role builds and full exported
sounding-event/rest equality are still mandatory for all four authored targets.

## Exact performance shortcuts

`Selector.extend` updates sufficient statistics by replacing the affected tail
and seam, retaining enough preceding context for source interval pairs,
oscillation and a complete possible home-theme match. A newly established home
or explicit tied continuation takes the complete-evaluation path. Pending-target
features are recalculated for the new horizon. Regression tests compare every
incremental record against canonical complete evaluation.

Retrieval caches internal route contributions but recalculates incoming pitch
relationships and the meaning of a leading rest. Weights are immutable validated
mappings; changing the mapping invalidates weighted caches. Past-frontier concrete
candidates are evicted after all incoming histories have been considered; selected
events remain in immutable search histories. These cache lifetimes are not musical
inputs or wall-clock search budgets.

Theme signature equality short-circuits on the first actual differing feature;
home signatures are cached while retaining their immutable home objects. The
comparison is exactly equivalent to normalized onset/duration/relative-pitch
tuple equality. It does not approximate thematic similarity or change scores.

Unconditional retrieval combines cached unary, transition, gap and pending-target
costs directly instead of allocating full feature reports for every rejected
action. Tests compare the result with the authoritative feature calculation
across all action families, incoming histories and weight changes. Learned joint
conditions and explicit tied fragments take the complete feature path; no missing
contextual term or altered tied duration is silently dropped by the shortcut.

Repeated endpoint retrieval is memoized only for the same immutable action
catalog, exact frontier, last three pitches/release, incoming sustained/rest
classification, pending contracts, weights and budget. Full home-aware candidate
evaluation still runs with the real history. Weight changes invalidate the cache;
retaining the catalog object prevents object-ID reuse. Tests distinguish pending
targets and incoming hold durations, and a complete four-bar rerun preserves all
events, candidate evaluations and frontier records.