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.