docs(scoring): document ConstraintSet::constraint_metadata_entries

crates/solverforge-scoring/WIREFRAME.md

@@ -451,7 +451,7 @@ Implementing it by hand is a supported extension point; the contract an implemen
 | `evaluate_all` | `fn evaluate_all(&self, solution: &S) -> Sc` | Sum all constraints |
 | `constraint_count` | `fn constraint_count(&self) -> usize` | Number of constraints |
 | `constraint_metadata` | `fn constraint_metadata(&self) -> Vec<ConstraintMetadata<'_>>` | Deduplicated borrowed ref/name/hardness metadata |
-| `constraint_metadata_entries` | `fn constraint_metadata_entries(&self) -> Vec<ConstraintMetadata<'_>>` | Hidden raw metadata entries in authored order |
+| `constraint_metadata_entries` | `fn constraint_metadata_entries(&self) -> Vec<ConstraintMetadata<'_>>` | Required: one entry per constraint in authored order, duplicates kept; tuples and chains concatenate their members' entries and `constraint_metadata` deduplicates them |
 | `evaluate_each` | `fn evaluate_each<'a>(&'a self, solution: &S) -> Vec<ConstraintResult<'a, Sc>>` | Per-constraint results |
 | `evaluate_detailed` | `fn evaluate_detailed<'a>(&'a self, solution: &S) -> Vec<ConstraintAnalysis<'a, Sc>>` | With match details |
 | `initialize_all` | `fn initialize_all(&mut self, solution: &S) -> Sc` | Initialize all for incremental |

crates/solverforge-scoring/public-api.txt

@@ -437,9 +437,10 @@ enum stream::ExistenceMode: pub enum ExistenceMode { Exists, NotExists, }
 enum stream::joiner::Strategy: pub enum Strategy { EquiHash, OrderedScan, IntervalNarrow, Scan, }
     stream::joiner::Strategy: pub const fn combine(self, other: Strategy) -> Strategy
 enum stream::relational::operator::ComplementView: pub enum ComplementView<'a, L, R, T> { Real(Pair<L, R>), Default(ProjectView<'a, L, T>), }
-trait api::constraint_set::ConstraintSet: pub trait ConstraintSet<S, Sc: Score>: Send + Sync { Show 16 methods // Required methods fn evaluate_all(&self, solution: &S) -> Sc; fn constraint_count(&self) -> usize; fn evaluate_each<'a>( &'a self, solution: &S, ) -> Vec<ConstraintResult<'a, Sc>>; fn evaluate_detailed<'a>( &'a self, solution: &S, ) -> Vec<ConstraintAnalysis<'a, Sc>>; fn initialize_all(&mut self, solution: &S) -> Sc; fn on_insert_all( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, ) -> Sc; fn on_retract_all( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, ) -> Sc; fn reset_all(&mut self); fn constraint_weight_refs<'a>(&'a self, refs: &mut Vec<&'a ConstraintRef>); fn evaluate_all_weighted(&self, solution: &S, multipliers: &[u32]) -> Sc; fn evaluate_each_weighted<'a>( &'a self, solution: &S, multipliers: &[u32], ) -> Vec<ConstraintResult<'a, Sc>>; fn evaluate_detailed_weighted<'a>( &'a self, solution: &S, multipliers: &[u32], ) -> Vec<ConstraintAnalysis<'a, Sc>>; fn initialize_all_weighted( &mut self, solution: &S, multipliers: &[u32], ) -> Sc; fn on_insert_all_weighted( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, multipliers: &[u32], ) -> Sc; fn on_retract_all_weighted( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, multipliers: &[u32], ) -> Sc; // Provided method fn constraint_metadata(&self) -> Vec<ConstraintMetadata<'_>> { ... } }
+trait api::constraint_set::ConstraintSet: pub trait ConstraintSet<S, Sc: Score>: Send + Sync { Show 17 methods // Required methods fn evaluate_all(&self, solution: &S) -> Sc; fn constraint_count(&self) -> usize; fn constraint_metadata_entries(&self) -> Vec<ConstraintMetadata<'_>>; fn evaluate_each<'a>( &'a self, solution: &S, ) -> Vec<ConstraintResult<'a, Sc>>; fn evaluate_detailed<'a>( &'a self, solution: &S, ) -> Vec<ConstraintAnalysis<'a, Sc>>; fn initialize_all(&mut self, solution: &S) -> Sc; fn on_insert_all( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, ) -> Sc; fn on_retract_all( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, ) -> Sc; fn reset_all(&mut self); fn constraint_weight_refs<'a>(&'a self, refs: &mut Vec<&'a ConstraintRef>); fn evaluate_all_weighted(&self, solution: &S, multipliers: &[u32]) -> Sc; fn evaluate_each_weighted<'a>( &'a self, solution: &S, multipliers: &[u32], ) -> Vec<ConstraintResult<'a, Sc>>; fn evaluate_detailed_weighted<'a>( &'a self, solution: &S, multipliers: &[u32], ) -> Vec<ConstraintAnalysis<'a, Sc>>; fn initialize_all_weighted( &mut self, solution: &S, multipliers: &[u32], ) -> Sc; fn on_insert_all_weighted( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, multipliers: &[u32], ) -> Sc; fn on_retract_all_weighted( &mut self, solution: &S, entity_index: usize, descriptor_index: usize, multipliers: &[u32], ) -> Sc; // Provided method fn constraint_metadata(&self) -> Vec<ConstraintMetadata<'_>> { ... } }
     api::constraint_set::ConstraintSet: fn evaluate_all(&self, solution: &S) -> Sc
     api::constraint_set::ConstraintSet: fn constraint_count(&self) -> usize
+    api::constraint_set::ConstraintSet: fn constraint_metadata_entries(&self) -> Vec<ConstraintMetadata<'_>>
     api::constraint_set::ConstraintSet: fn evaluate_each<'a>(&'a self, solution: &S) -> Vec<ConstraintResult<'a, Sc>>
     api::constraint_set::ConstraintSet: fn evaluate_detailed<'a>( &'a self, solution: &S, ) -> Vec<ConstraintAnalysis<'a, Sc>>
     api::constraint_set::ConstraintSet: fn initialize_all(&mut self, solution: &S) -> Sc

crates/solverforge-scoring/src/api/constraint_set/incremental.rs

@@ -292,8 +292,15 @@ pub trait ConstraintSet<S, Sc: Score>: Send + Sync {
         deduplicate_constraint_metadata(self.constraint_metadata_entries())
     }
 
-    /// Returns one metadata entry per constraint in authored order.
-    #[doc(hidden)]
+    /// Returns one metadata entry per constraint in authored order, keeping
+    /// duplicates.
+    ///
+    /// This is the method an implementation provides: tuples and chains build
+    /// their entries from their members' entries, and
+    /// [`constraint_metadata`](Self::constraint_metadata) deduplicates the
+    /// result. A set of one constraint returns its single entry; a set that
+    /// scores several named constraints returns one entry per name, in the
+    /// order its terminals were authored.
     fn constraint_metadata_entries(&self) -> Vec<ConstraintMetadata<'_>>;
 
     /// Evaluates each constraint individually and returns per-constraint results.

docs/extend-scoring.md

@@ -115,7 +115,9 @@ slot per named constraint through `constraint_weight_refs` and scale each
 one's contribution by its own slot; never apply one multiplier to a delta that
 sums several named constraints. A hand-written `ConstraintSet` must implement
 the weighted methods by splitting `multipliers` across its children in
-`constraint_weight_refs` order.
+`constraint_weight_refs` order, and `constraint_metadata_entries` by returning
+one entry per named constraint in authored order, duplicates kept;
+`constraint_metadata` deduplicates them.
 
 ## Evaluation ownership