Trait Objective 

pub trait Objective<T>: Send + Sync {
    // Required method
    fn score(&self, candidate: &T, context: &ObjectiveContext) -> f64;

    // Provided methods
    fn precision(&self, _candidate: &T, _context: &ObjectiveContext) -> f64 { ... }
    fn passes_score(&self, score: f64, context: &ObjectiveContext) -> bool { ... }
    fn passes(&self, candidate: &T, context: &ObjectiveContext) -> bool { ... }
    fn batch_score(
        &self,
        candidates: &[T],
        context: &ObjectiveContext,
    ) -> Vec<(usize, f64)> { ... }
    fn select<'a>(
        &self,
        candidates: &'a [T],
        context: &ObjectiveContext,
    ) -> ObjectiveResult<Selection<&'a T>> { ... }
    fn select_top<'a>(
        &self,
        candidates: &'a [T],
        n: usize,
        context: &ObjectiveContext,
    ) -> Vec<Selection<&'a T>> { ... }
    fn name(&self) -> &str { ... }
}

Trait for objective functions that select from candidates.

An objective function is a measurement operator that collapses a space of possibilities into a single selection. Objectives are deterministic, composable, and introspectable.

Required Methods

fn score(&self, candidate: &T, context: &ObjectiveContext) -> f64

Evaluate a single candidate.

Provided Methods

fn precision(&self, _candidate: &T, _context: &ObjectiveContext) -> f64

Precision (inverse variance) estimate for the score of a candidate.

Default is 1.0 (fully trusted). Override when score reliability varies across candidates — e.g., an embedding model that returns a confidence alongside the similarity score. The effective ranking value used by the default select / select_top implementations is score * precision (ADR-059, Predictive Coding).

When overriding, return values in (0, 1]. Non-finite values are treated as 1.0 by the default implementations.

fn passes_score(&self, score: f64, context: &ObjectiveContext) -> bool

Check if a score passes the threshold.

Non-finite scores never pass.

fn passes(&self, candidate: &T, context: &ObjectiveContext) -> bool

Check if a candidate passes the threshold.

fn batch_score( &self, candidates: &[T], context: &ObjectiveContext, ) -> Vec<(usize, f64)>

Score a batch of candidates and return the passing (index, score) pairs.

The default implementation is a scalar fallback. Objectives with SIMD-friendly layouts can override this hook for higher throughput.

fn select<'a>( &self, candidates: &'a [T], context: &ObjectiveContext, ) -> ObjectiveResult<Selection<&'a T>>

Select the best candidate from a list.

Ranking uses score * precision so that unreliable high-scores do not dominate over lower-scoring but precise candidates (ADR-059). When all precisions are 1.0 (the default), ranking is identical to raw score order.

fn select_top<'a>( &self, candidates: &'a [T], n: usize, context: &ObjectiveContext, ) -> Vec<Selection<&'a T>>

Select the top N candidates.

Ranking uses score * precision (ADR-059). Small n (≤96) uses a sorted small-vector path with binary-search insertion. Large n uses a worst-first heap.

fn name(&self) -> &str

Get the name of this objective.

Implementors

impl<T, F> Objective<T> for F

where F: Fn(&T, &ObjectiveContext) -> f64 + Send + Sync,

Implement Objective for closures.

impl<T, O: Objective<T>> Objective<T> for ScaleObjective<O>

impl<T: HasImportance + Send + Sync> Objective<T> for ImportanceObjective

impl<T: HasTimestamp + HasImportance + Send + Sync> Objective<T> for RelevanceObjective

impl<T: HasTimestamp + Send + Sync> Objective<T> for RecencyObjective

impl<T: Send + Sync> Objective<T> for ConsensusObjective<T>

impl<T: Send + Sync> Objective<T> for NegateObjective<T>

impl<T: Send + Sync> Objective<T> for PriorityObjective<T>

impl<T: Send + Sync> Objective<T> for UnionObjective<T>

impl<T: Send + Sync> Objective<T> for WeightedObjective<T>

impl<T: Send + Sync, F> Objective<T> for FirstMatchObjective<T, F>

where F: Fn(&T) -> bool + Send + Sync,

impl<T: Send + Sync, F> Objective<T> for MaxScoreObjective<T, F>

where F: Fn(&T) -> f64 + Send + Sync,

impl<T: Send + Sync, F> Objective<T> for ThresholdObjective<T, F>

where F: Fn(&T) -> f64 + Send + Sync,