Struct LanguageHint 

#[non_exhaustive]
pub struct LanguageHint {
    pub lang: String,
    pub source: LangHintSource,
    pub confidence: f32,
}

v0.10 Sprint 2 — typed lang hint wrapper(Decision A-prime)。

设计意图:替代裸 Option<&str> 给 SDK consumer / 未来 firewall lang-aware 路径用;强制 provenance + confidence,low-conf 一律 fail-closed 退化。

典型用法(SDK consumer):

use vigil_redaction::lang_hint::{LanguageHint, LangHintSource};

// caller 知道用户 locale → 高信任
let hint = LanguageHint::caller_provided("de");

// 启发式 detect → advisory,low-conf 自动 fail-closed
let hint = LanguageHint::heuristic("de", 0.4);  // confidence 太低,into_lang_str → None

SemVer:#[non_exhaustive] — 未来加字段(如 audit_id / provider_chain) 不破;pub fields 可读,struct literal 构造仅 crate 内可用。

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

lang: String

ISO 639-1 lowercase("en" / "de" / "it" / "fr" / …);与 fixture lang 字段对齐

source: LangHintSource

信息来源(用于 audit trail + 可信度决策)

confidence: f32

置信度 [0.0, 1.0];low-conf(< 0.5)into_lang_str 一律返 None(fail-closed 退化 baseline path,避免误降 policy)

Implementations

impl LanguageHint

pub fn caller_provided(lang: impl Into<String>) -> LanguageHint

caller 显式传入(CallerProvided source,confidence = 1.0)。 适用:用户 locale 设置 / 业务上下文 / 已校验输入。

pub fn fixture(lang: impl Into<String>) -> LanguageHint

fixture / 测试场景(FixtureExperimental source,confidence = 1.0)。 仅非 production;典型 release-gate / spike-gate / fixture lang 字段透传。

pub fn heuristic(lang: impl Into<String>, confidence: f32) -> LanguageHint

启发式 detect(Heuristic source,caller 给 confidence)。 决策不可信:即使 confidence = 1.0,is_trusted 返 false(由 LangHintSource 静态判定);仅 advisory(diagnose / suggestion UI)。 confidence < 0.5 时 into_lang_str 也返 None。

pub fn detect(text: &str) -> LanguageHint

v0.10 Sprint 6 — 启发式 lang detect(advisory only)。

调用 detect_lang_heuristic 内部启发式(unicode 字符集 + 关键词),返 LanguageHint with LangHintSource::Heuristic。 始终返 Heuristic — lang_str() 永返 None,无法触发 firewall 决策路径。

适用场景:

• fixture lang 字段标注辅助(P1.0 启发式同口径,但用 Rust 端版本)
• SDK consumer 诊断 UI / 建议性显示
• 永不作 production 决策权威(feedback_lang_review_authoritative 约束)

pub fn lang_str(&self) -> Option<&str>

fail-closed 转换:返 Option<&str>(走 scan_text_with_engine_with_lang)。

决策规则:

• confidence < LANG_HINT_TRUSTED_CONFIDENCE(0.5)→ None(退化 baseline)
• LangHintSource::Heuristic → None(无论 confidence,启发式不可信)
• 其他(CallerProvided / FixtureExperimental + confidence ≥ 0.5)→ Some(&lang)

这是 D=C 决议下的 SDK 边界 — caller 即使传 Heuristic,也不会触发 lang-conditional threshold(防 production 误降 policy)。

Trait Implementations

impl Clone for LanguageHint

fn clone(&self) -> LanguageHint

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LanguageHint

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.