zeppelin_embed/fusion/
rules.rs

1use super::{DEFAULT_ALPHA, FusionError};
2
3/// Version of the rule data interpreted by fusion reports. Version 2
4/// (2026-08-26) turned the rules off by default on measured evidence.
5pub const ALPHA_POLICY_VERSION: u16 = 2;
6
7/// MEASURED HARMFUL AT EVERY CELL on BEIR SciFact
8/// (`tasks/evidence/17-fusion.md`): with rules on, this pair scores nDCG@10
9/// 0.7458 against the 0.7642 no-rule baseline, and no `(threshold,
10/// rule_alpha)` cell in a 28-cell sweep beat the baseline. The rules are
11/// therefore opt-in (`HybridQuery::with_rules`) and this value is retained
12/// only for a caller who has measured an identifier-heavy corpus of their
13/// own; it is not a quality claim.
14pub const LEXICAL_RULE_ALPHA: f64 = 0.4;
15
16/// A query token at or below this document frequency is considered rare.
17/// Measured with `LEXICAL_RULE_ALPHA` above: on SciFact the min-over-terms
18/// signal fires on 211 of 300 queries at this value because any
19/// out-of-vocabulary token trips it, so it does not isolate rare exact
20/// tokens there. Opt-in only; see `LEXICAL_RULE_ALPHA`.
21pub const RARE_DOCUMENT_FREQUENCY_THRESHOLD: u64 = 5;
22
23/// Stable rule names emitted by the fusion report.
24#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
25pub enum FusionRule {
26    /// Query contains a quoted phrase.
27    QuotedPhrase,
28    /// Query contains an exact token at or below the rarity threshold.
29    RareExactToken,
30    /// Query contains an identifier-class token.
31    IdentifierToken,
32}
33
34/// Caller-computed deterministic query-shape facts.
35#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
36pub struct RuleSignals {
37    /// Whether the structured query contains a quoted phrase.
38    pub quoted_phrase: bool,
39    /// Lowest exact-token document frequency, absent when no exact token exists.
40    pub rarest_exact_document_frequency: Option<u64>,
41    /// Whether token classification found an identifier.
42    pub identifier_token: bool,
43}
44
45impl RuleSignals {
46    /// Constructs a signal set with no matching rules.
47    #[must_use]
48    pub const fn none() -> Self {
49        Self {
50            quoted_phrase: false,
51            rarest_exact_document_frequency: None,
52            identifier_token: false,
53        }
54    }
55}
56
57pub(crate) fn effective_alpha(
58    query: &super::HybridQuery,
59) -> Result<(f64, Vec<FusionRule>), FusionError> {
60    if let Some(alpha) = query.alpha {
61        validate(alpha)?;
62        return Ok((alpha, Vec::new()));
63    }
64    validate(DEFAULT_ALPHA)?;
65    if !query.rules_enabled {
66        return Ok((DEFAULT_ALPHA, Vec::new()));
67    }
68    let mut applied = Vec::new();
69    if query.rule_signals.quoted_phrase {
70        applied.push(FusionRule::QuotedPhrase);
71    }
72    if query
73        .rule_signals
74        .rarest_exact_document_frequency
75        .is_some_and(|frequency| frequency <= RARE_DOCUMENT_FREQUENCY_THRESHOLD)
76    {
77        applied.push(FusionRule::RareExactToken);
78    }
79    if query.rule_signals.identifier_token {
80        applied.push(FusionRule::IdentifierToken);
81    }
82    if applied.is_empty() {
83        Ok((DEFAULT_ALPHA, applied))
84    } else {
85        Ok((LEXICAL_RULE_ALPHA, applied))
86    }
87}
88
89fn validate(alpha: f64) -> Result<(), FusionError> {
90    if alpha.is_finite() && (0.0..=1.0).contains(&alpha) {
91        Ok(())
92    } else {
93        Err(FusionError::InvalidAlpha(alpha))
94    }
95}
zeppelin_embed/fusion/rules.rs

zeppelin_embed/fusion/
rules.rs
