Cleanup

docs/composer/evaluation_contract.md

@@ -1,15 +1,107 @@
-# Authoritative action evaluation
+# Canonical phrase evaluation and shared learning
 
-`selection.Selector.evaluate` returns `Evaluation(version='action-selection-1')`: raw normalized values, enabled weights, exact rational contributions, total and denominators. Ranking uses exactly the sum of reported contributions. Tied continuations merge before evaluation; repeated attacks remain distinct.
+`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 scope is one complete musical action, not a chorus. Alternatives compete by cost per exact quarter; compound routes remain indivisible. Prefix and reporting-phrase totals sum local decisions. They are diagnostics, not global objectives or partition-invariant phrase quality scores. Computational partitioning that preserves the action objects does not change evaluation. Changing musical action boundaries can change the local search objective.
+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.
 
-Fixed priors address excessive leaps, register distance outside a soft corridor, oscillation, repeated attacks, unprepared space, repeated rests, source interval relationships, actual theme relationships, sustained chord-tone arrivals and directed steps. Shared integer coefficients can distinguish action kind, duration, chord-relative pitch role, incoming interval, relative metric position, motion direction, register band, source rhythm, realized theme evidence and context of silence. Title, filename, absolute bar index, reference hash and event lookups are not allowed features.
+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.
 
-Silence has no pitch/register value. A rest after an arrival differs from an interruption or repeated rest. A sustain is one attack with its complete duration. Approved expression is validated by contract rather than automatically rewarded or penalized as chromatic.
+## Development learning
 
-Hard validity remains separate: mapped collections, typed exceptions, exact target register/time/duration, pending deadlines, rhythm groups, physical domain, monophony and source-derived allocation. Pending obligations filter the frontier before pruning. Final placement cannot change selected pitches or rhythm.
+`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.
 
-The optional fitter uses an integer early-update structured perceptron, at most 200 passes. Coefficients are shared between songs within each role. Its checkpoint prefers fewer incorrect rollouts, then longer exact prefixes, then smaller coefficients. This differs from minimizing whole-output discrepancy; full export comparison remains the acceptance gate. Fitted artifacts stay under `build/` until a verified model is deliberately promoted. Constructibility alone is not grounds for promotion.
+`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.
 
-Synthetic tests check contribution sums, weight counterfactuals, tied-event invariance, forbidden feature names and a learnable two-choice fitting problem. They establish mechanics, not that this finite feature set expresses the four desired decisions or predicts musical preference.
+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.