gaze_types/

lib.rs

#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod inspection;
pub mod nym;
pub mod payment_card;
pub mod redaction_marker;

use std::cell::Cell;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::fmt;
use std::ops::Range;

use serde::{Deserialize, Serialize};
use sha3::{Digest, Keccak256};
use thiserror::Error;

/// What a detection rests on, declared by the recognizer or detector that emits it.
///
/// The repeat-value sweep copies only [`EvidenceKind::Rule`] values to every other occurrence
/// in the document and in later turns of the session, so a model's mistake is never spread.
/// The default is [`EvidenceKind::Learned`]: an emitter that declares nothing is never
/// propagated. Declare `Rule` only when every candidate comes from a deterministic rule a
/// reviewer can read (a regex, a dictionary term, a cue-anchored match).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum EvidenceKind {
    /// A model or heuristic decided: NER, a model judge, a span licensed by a model span.
    #[default]
    Learned,
    /// A deterministic rule decided.
    Rule,
}

/// Matching variants available to a caller-known record. Unmeasured variants
/// require an explicit adopter opt-in in the context envelope.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum RecordMatchKind {
    Exact,
    WhitespaceFlexible,
    CaseFolded,
    WhitespaceCaseFolded,
    CorroboratedSingle,
}

/// Shared detector contract for text-only PII detection.
pub trait Detector: Send + Sync {
    /// Detect PII spans in the supplied input string.
    fn detect(&self, input: &str) -> Vec<Detection>;

    /// What this detector's detections rest on. Defaults to [`EvidenceKind::Learned`], which
    /// the repeat-value sweep never propagates; see [`EvidenceKind`].
    fn evidence(&self) -> EvidenceKind {
        EvidenceKind::Learned
    }

    /// Fallible detection entrypoint for detectors backed by runtime systems.
    fn try_detect(&self, input: &str) -> Result<Vec<Detection>, RecognizerRuntimeError> {
        Ok(self.detect(input))
    }
}

/// Runtime failure raised by a recognizer or detector backend during detection.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct RecognizerRuntimeError {
    pub recognizer_id: String,
    pub message: String,
}

impl RecognizerRuntimeError {
    pub fn new(recognizer_id: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            recognizer_id: recognizer_id.into(),
            message: message.into(),
        }
    }
}

impl fmt::Display for RecognizerRuntimeError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "recognizer '{}' backend failed: {}",
            self.recognizer_id, self.message
        )
    }
}

impl std::error::Error for RecognizerRuntimeError {}

/// The category of a detected PII span.
///
/// Built-in variants: `Email`, `Name`, `Location`, `Organization`. Tenant-specific PII
/// (case references, titles, internal codes) is carried as `PiiClass::Custom(String)`.
/// **There is no `Phone` variant** -- phone detection is provided by recognizers in
/// `gaze-recognizers` and surfaces as either a `Custom("phone")` class or a class
/// defined by a rulepack.
///
/// `PiiClass` is exhaustive. Match every variant explicitly so new built-in classes
/// force call sites to review their handling at compile time:
///
/// ```rust
/// use gaze_types::PiiClass;
///
/// fn label(class: &PiiClass) -> &'static str {
///     match class {
///         PiiClass::Email        => "email",
///         PiiClass::Name         => "name",
///         PiiClass::Location     => "location",
///         PiiClass::Organization => "org",
///         PiiClass::Custom(_)    => "pii",
///     }
/// }
/// ```
///
/// Policy TOML uses the lowercase forms `email` / `name` / `location` / `organization`,
/// and tenant classes are spelled like `custom:case_ref` (lowercase, snake_case).
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum PiiClass {
    /// Email address class.
    Email,
    /// Person name class.
    Name,
    /// Location class.
    Location,
    /// Organization class.
    Organization,
    /// Tenant- or policy-defined class.
    Custom(String),
}

/// A custom class must contain at least one ASCII letter or digit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[error("custom class name normalizes to empty")]
pub struct EmptyCustomClassName;

/// Recognizer id of the bundled NER recognizer. Pipeline stages that treat NER evidence
/// specially (street-corroborated house numbers) match on this, so a rename cannot silently
/// switch them off.
pub const NER_RECOGNIZER_ID: &str = "ner";

/// Built-in class labels in stable display order.
pub const BUILTIN_CLASS_NAMES: &[&str] = &["Email", "Name", "Location", "Organization"];

/// Family names reserved for bundled collision-policy rulepacks.
///
/// Adopter policy-level custom recognizers cannot claim these names because bundled
/// families are part of the core disambiguation contract.
pub const RESERVED_BUNDLED_FAMILIES: &[&str] = &[
    "us-9-digit-id",
    "iberian-id",
    "payment-card-or-iban",
    "phone-or-imei",
    "vin-or-serial",
    "mac-or-hex",
    "passport-or-doc-support",
    "national-13-digit",
    "italian-cf-or-serial",
    "german-personalausweis",
    "swedish-personnummer",
    "finnish-hetu",
];

pub const RESTORE_PHASE_MANIFEST_LOOKUP: u32 = 1 << 0;
pub const RESTORE_PHASE_UNKNOWN_TOKEN_SCAN: u32 = 1 << 1;
pub const RESTORE_PHASE_MANIFEST_BYPASS_SCAN: u32 = 1 << 2;
pub const RESTORE_PHASE_FRESH_PII_SCAN: u32 = 1 << 3;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct RestoredText {
    pub text: String,
}

impl RestoredText {
    pub fn new(text: impl Into<String>) -> Self {
        Self { text: text.into() }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RestorePolicy {
    Strict,
    Lenient,
}

impl RestorePolicy {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Strict => "strict",
            Self::Lenient => "lenient",
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RestoreDecision {
    Success,
    Partial,
    Failed,
}

impl RestoreDecision {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Success => "success",
            Self::Partial => "partial",
            Self::Failed => "failed",
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct RestoreTelemetry {
    /// Unmapped canonical placeholders or incomplete prefixed wrappers outside authorized output.
    pub unknown_token_count: u64,
    /// Audit-only broad bare identifier shapes outside authorized restore output.
    pub manifest_bypass_count: u64,
    /// All unprefixed trap shapes in restored text, including authorized values.
    #[serde(default)]
    pub trap_shape_count: u64,
    pub fresh_pii_detected_count: u64,
    pub restore_policy: RestorePolicy,
    pub restore_decision: RestoreDecision,
    pub phase_execution_mask: u32,
}

impl RestoreTelemetry {
    pub fn new(restore_policy: RestorePolicy) -> Self {
        Self {
            unknown_token_count: 0,
            manifest_bypass_count: 0,
            trap_shape_count: 0,
            fresh_pii_detected_count: 0,
            restore_policy,
            restore_decision: RestoreDecision::Success,
            phase_execution_mask: 0,
        }
    }

    pub fn restore_policy_str(&self) -> &'static str {
        self.restore_policy.as_str()
    }

    pub fn restore_decision_str(&self) -> &'static str {
        self.restore_decision.as_str()
    }
}

/// Collision-family membership metadata for one recognizer.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct CollisionMembership {
    /// Cross-class family name.
    pub family: String,
    /// Variant name within the family.
    pub variant: String,
    /// Lower values win when two variants in the same family overlap.
    pub precedence: u32,
    /// Optional anchor variant required by later ambiguity handling.
    pub mandatory_anchor: Option<String>,
}

impl CollisionMembership {
    /// Builds collision-family membership metadata.
    pub fn new(
        family: impl Into<String>,
        variant: impl Into<String>,
        precedence: u32,
        mandatory_anchor: Option<String>,
    ) -> Self {
        Self {
            family: family.into(),
            variant: variant.into(),
            precedence,
            mandatory_anchor,
        }
    }
}

impl PiiClass {
    /// Parses a policy class name into the shared class vocabulary.
    pub fn from_policy_name(input: &str) -> Option<Self> {
        let trimmed = input.trim();
        match trimmed.to_ascii_lowercase().as_str() {
            "email" => Some(Self::Email),
            "name" => Some(Self::Name),
            "location" => Some(Self::Location),
            "organization" => Some(Self::Organization),
            _ => trimmed
                .split_once(':')
                .filter(|(namespace, _)| namespace.eq_ignore_ascii_case("custom"))
                .and_then(|(_, name)| Self::from_custom_policy_suffix(name)),
        }
    }

    fn from_custom_policy_suffix(name: &str) -> Option<Self> {
        let name = name.trim();
        if let Some(family) = name.strip_prefix("family:") {
            (!family.trim().is_empty()).then(|| Self::family(family))
        } else {
            Self::custom(name).ok()
        }
    }

    /// Returns the built-in class variants.
    pub fn builtin_variants() -> &'static [PiiClass] {
        &[
            PiiClass::Email,
            PiiClass::Name,
            PiiClass::Location,
            PiiClass::Organization,
        ]
    }

    /// Builds a normalized custom class name.
    ///
    /// Returns [`EmptyCustomClassName`] when no ASCII letter or digit remains.
    pub fn custom(name: &str) -> Result<Self, EmptyCustomClassName> {
        let mut normalized = String::new();
        let mut pending_underscore = false;
        for ch in name.trim().chars() {
            if ch.is_ascii_alphanumeric() {
                if pending_underscore && !normalized.is_empty() {
                    normalized.push('_');
                }
                normalized.push(ch.to_ascii_lowercase());
                pending_underscore = false;
            } else {
                pending_underscore = true;
            }
        }

        let class = Self::Custom(normalized);
        class.validate_custom_name()?;
        Ok(class)
    }

    /// Checks names supplied through the public enum before token emission.
    pub fn validate_custom_name(&self) -> Result<(), EmptyCustomClassName> {
        if matches!(self, Self::Custom(name) if !name.chars().any(|ch| ch.is_ascii_alphanumeric()))
        {
            return Err(EmptyCustomClassName);
        }
        Ok(())
    }

    /// Builds a collision-family class without normalizing its reserved namespace.
    pub fn family(name: &str) -> Self {
        Self::Custom(format!("family:{}", name.trim()))
    }

    /// Returns the normalized custom class name for custom classes.
    pub fn as_custom_name(&self) -> Option<&str> {
        match self {
            Self::Custom(name) => Some(name.as_str()),
            Self::Email | Self::Name | Self::Location | Self::Organization => None,
        }
    }

    /// Returns the collision-family name for family classes.
    pub fn as_family_name(&self) -> Option<&str> {
        self.as_custom_name()?.strip_prefix("family:")
    }

    /// Returns the audit/token display label for this class.
    pub fn class_name(&self) -> String {
        match self {
            Self::Email => BUILTIN_CLASS_NAMES[0].to_string(),
            Self::Name => BUILTIN_CLASS_NAMES[1].to_string(),
            Self::Location => BUILTIN_CLASS_NAMES[2].to_string(),
            Self::Organization => BUILTIN_CLASS_NAMES[3].to_string(),
            Self::Custom(name) => format!("Custom:{name}"),
        }
    }

    /// Returns the canonical audit/serde label for this class.
    pub fn to_canonical_str(&self) -> String {
        match self {
            Self::Email => "email".to_string(),
            Self::Name => "name".to_string(),
            Self::Location => "location".to_string(),
            Self::Organization => "organization".to_string(),
            Self::Custom(name) => format!("custom:{name}"),
        }
    }

    /// Parses the canonical audit/serde label for a PII class.
    pub fn from_canonical_str(value: &str) -> Option<Self> {
        match value {
            "email" | "Email" => Some(Self::Email),
            "name" | "Name" => Some(Self::Name),
            "location" | "Location" => Some(Self::Location),
            "organization" | "Organization" => Some(Self::Organization),
            custom if custom.starts_with("custom:") => {
                let name = &custom["custom:".len()..];
                (!name.is_empty()).then(|| Self::Custom(name.to_string()))
            }
            _ => None,
        }
    }
}

#[cfg(test)]
mod pii_class_tests {
    use super::*;

    #[test]
    fn bundled_family_policy_names_round_trip_without_normalization() {
        for family in RESERVED_BUNDLED_FAMILIES {
            let policy_name = format!("custom:family:{family}");
            let class = PiiClass::from_policy_name(&policy_name).expect("family policy class");

            assert_eq!(class.to_canonical_str(), policy_name);
            assert_eq!(class.as_family_name(), Some(*family));
        }
    }
}

/// Audit-canonical form of [`PiiClass`].
///
/// Serializes as `"email"`, `"name"`, `"custom:foo"`, and similar canonical
/// strings. Use this wrapper for audit-row JSON only. Session snapshots use
/// bare [`PiiClass`] serde so their byte shape stays stable.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct PiiClassAudit(pub PiiClass);

impl PiiClassAudit {
    /// Builds an audit-canonical class wrapper.
    pub fn new(class: PiiClass) -> Self {
        Self(class)
    }

    /// Unwraps the underlying class.
    pub fn into_inner(self) -> PiiClass {
        self.0
    }
}

impl Serialize for PiiClassAudit {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(&self.0.to_canonical_str())
    }
}

impl<'de> Deserialize<'de> for PiiClassAudit {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        PiiClass::from_canonical_str(&value)
            .map(Self)
            .ok_or_else(|| {
                serde::de::Error::custom(format!("unknown PiiClass canonical form: {value}"))
            })
    }
}

mod pii_class_audit_serde {
    use super::{PiiClass, PiiClassAudit};
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    pub fn serialize<S>(class: &PiiClass, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        PiiClassAudit::new(class.clone()).serialize(serializer)
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<PiiClass, D::Error>
    where
        D: Deserializer<'de>,
    {
        Ok(PiiClassAudit::deserialize(deserializer)?.into_inner())
    }
}

/// A candidate recognizer/class pair that lost ambiguity resolution.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct LosingCandidate {
    /// PII class proposed by the losing recognizer.
    #[serde(with = "pii_class_audit_serde")]
    pub class: PiiClass,
    /// Stable recognizer identifier for traceability.
    pub recognizer_id: String,
}

impl LosingCandidate {
    /// Builds a losing ambiguity candidate.
    pub fn new(class: PiiClass, recognizer_id: impl Into<String>) -> Self {
        Self {
            class,
            recognizer_id: recognizer_id.into(),
        }
    }
}

/// Where a family-level token's policy action came from when no rule named
/// the family class: the strictest action among the family's member classes'
/// rules and the family's own default, see [`Action::strictness_rank`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct DerivedFamilyAction {
    /// The action applied to the family token.
    pub action: Action,
    /// The member class whose explicit rule set the action. `None` when the
    /// family's own default rule applied: no member's own rule reached the
    /// derived strictness. Ties between members go to the lowest class in
    /// `PiiClass` order.
    #[serde(with = "optional_pii_class_audit_serde", default)]
    pub member_class: Option<PiiClass>,
}

impl DerivedFamilyAction {
    /// Records a family action derived from `member_class` (or the default).
    pub fn new(action: Action, member_class: Option<PiiClass>) -> Self {
        Self {
            action,
            member_class,
        }
    }
}

mod optional_pii_class_audit_serde {
    use super::{PiiClass, PiiClassAudit};
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    pub fn serialize<S>(class: &Option<PiiClass>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        class.clone().map(PiiClassAudit::new).serialize(serializer)
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<PiiClass>, D::Error>
    where
        D: Deserializer<'de>,
    {
        Ok(Option::<PiiClassAudit>::deserialize(deserializer)?.map(PiiClassAudit::into_inner))
    }
}

/// Structured metadata describing an ambiguity outcome.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct AmbiguityRecord {
    /// The family-level class assigned when disambiguation failed.
    #[serde(with = "pii_class_audit_serde")]
    pub ambiguity_class: PiiClass,
    /// Variants that could not be disambiguated.
    ///
    /// Producers must keep this list stable by sorting `recognizer_id` ascending.
    pub losing_candidates: Vec<LosingCandidate>,
    /// Why disambiguation failed.
    pub reason: AmbiguityReason,
    /// How the family token's action was chosen when the policy named no rule
    /// for the family class. Absent when an explicit family rule applied, and
    /// on rows written before this field existed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub derived_action: Option<DerivedFamilyAction>,
}

impl AmbiguityRecord {
    /// Builds a structured ambiguity record.
    pub fn new(
        ambiguity_class: PiiClass,
        losing_candidates: Vec<LosingCandidate>,
        reason: AmbiguityReason,
    ) -> Self {
        Self {
            ambiguity_class,
            losing_candidates,
            reason,
            derived_action: None,
        }
    }

    /// Records how the family token's action was derived.
    pub fn with_derived_action(mut self, derived: DerivedFamilyAction) -> Self {
        self.derived_action = Some(derived);
        self
    }
}

/// Closed set of ambiguity outcomes recorded by the audit side-channel.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum AmbiguityReason {
    /// Span matched a multi-recognizer family and no anchor cue resolved it.
    NoAnchor,
    /// Multiple validator-stage recognizers remained viable for the same span.
    ValidatorIndeterminate,
    /// Span matched recognizers across two or more distinct PII class families.
    MultiFamilyMatch,
    /// Multiple variants had the same precedence and no discriminator resolved them.
    PrecedenceTie,
}

/// Closed pre-resolution refusal reasons recorded by audit metadata.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum ValidatorFailReason {
    /// A rulepack rejection guard refused the original regex capture.
    RegexGuardRejected,
    /// Luhn checksum validation failed.
    LuhnFailed,
    /// IBAN MOD-97 validation failed.
    IbanMod97Failed,
    /// Email RFC-style validation failed.
    #[serde(alias = "email_rfc_failed")]
    EmailRfcRejected,
    /// E.164 phone validation failed.
    #[serde(alias = "e164_phone_failed")]
    PhoneE164Rejected,
    /// National phone parser accepted the number but region validation failed.
    PhoneNationalRegionMismatch,
    /// IPv4 parser rejected the candidate.
    Ipv4ParseFailed,
    /// IPv6 parser rejected the candidate.
    Ipv6ParseFailed,
    /// Built-in IPv4 rule excluded an RFC 5737 documentation address.
    Ipv4DocumentationRange,
    /// Built-in IPv6 rule excluded an RFC 3849 or embedded RFC 5737 address.
    Ipv6DocumentationRange,
    /// EIP-55 Ethereum checksum validation failed.
    EthEip55ChecksumFailed,
    /// Aadhaar Verhoeff checksum validation failed.
    AadhaarVerhoeffFailed,
    /// French NIR MOD-97 key validation failed.
    FrNirMod97Failed,
    /// German Steuer-ID MOD 11,10 checksum validation failed.
    DeSteuerIdMod1110Failed,
    /// Dutch BSN MOD-11 checksum validation failed.
    BsnMod11Failed,
    /// Brazilian CPF MOD-11 checksum validation failed.
    CpfMod11Failed,
    /// Brazilian CNPJ MOD-11 checksum validation failed.
    CnpjMod11Failed,
    /// UK NHS number MOD-11 checksum validation failed.
    UkNhsMod11Failed,
    /// Built-in IPv4 rule excluded a loopback address (127.0.0.0/8).
    Ipv4LoopbackRange,
    /// Built-in IPv6 rule excluded a loopback address (`::1`, or an IPv4-mapped or IPv4-compatible
    /// 127.0.0.0/8 address).
    Ipv6LoopbackRange,
}

impl ValidatorFailReason {
    /// Every variant, for closed-vocabulary checks (component ledger records).
    #[doc(hidden)]
    pub const ALL: &'static [Self] = &[
        Self::RegexGuardRejected,
        Self::LuhnFailed,
        Self::IbanMod97Failed,
        Self::EmailRfcRejected,
        Self::PhoneE164Rejected,
        Self::PhoneNationalRegionMismatch,
        Self::Ipv4ParseFailed,
        Self::Ipv6ParseFailed,
        Self::Ipv4DocumentationRange,
        Self::Ipv6DocumentationRange,
        Self::EthEip55ChecksumFailed,
        Self::AadhaarVerhoeffFailed,
        Self::FrNirMod97Failed,
        Self::DeSteuerIdMod1110Failed,
        Self::BsnMod11Failed,
        Self::CpfMod11Failed,
        Self::CnpjMod11Failed,
        Self::UkNhsMod11Failed,
        Self::Ipv4LoopbackRange,
        Self::Ipv6LoopbackRange,
    ];

    /// Fails to compile when a variant is added without extending [`Self::ALL`].
    #[allow(dead_code)]
    const fn all_is_exhaustive(value: Self) {
        match value {
            Self::RegexGuardRejected
            | Self::LuhnFailed
            | Self::IbanMod97Failed
            | Self::EmailRfcRejected
            | Self::PhoneE164Rejected
            | Self::PhoneNationalRegionMismatch
            | Self::Ipv4ParseFailed
            | Self::Ipv6ParseFailed
            | Self::Ipv4DocumentationRange
            | Self::Ipv6DocumentationRange
            | Self::EthEip55ChecksumFailed
            | Self::AadhaarVerhoeffFailed
            | Self::FrNirMod97Failed
            | Self::DeSteuerIdMod1110Failed
            | Self::BsnMod11Failed
            | Self::CpfMod11Failed
            | Self::CnpjMod11Failed
            | Self::UkNhsMod11Failed
            | Self::Ipv4LoopbackRange
            | Self::Ipv6LoopbackRange => {}
        }
    }
}

/// Field separators that the bundled labelled identifier rules must all accept.
pub const LABELLED_FIELD_CONNECTORS: &[char] = &[':', '=', '|', '\t', ',', ';', '-'];

/// Why a labelled identifier scan stopped or exceeded its usual precision bound.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum LabelledValueScanReason {
    /// The complete value run exceeded four groups or forty bytes.
    LimitExceeded,
    /// A date starts the next field after the captured identifier.
    DateBoundary,
    /// A labelled field starts after the captured identifier.
    LabelBoundary,
    /// A different recognizer claims the following value.
    OtherClassBoundary,
}

/// Typed validator outcome used by the pre-resolver validator-veto phase.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum ValidatorOutcome {
    /// Candidate passed validation; canonical form may be supplied by the validator.
    Pass { canonical_form: Option<String> },
    /// Candidate failed validation with a closed, auditable reason.
    Fail { reason: ValidatorFailReason },
    /// Recognizer has no validator for this candidate.
    NotApplicable,
}

/// Error returned when a rulepack names a validator unsupported by this build.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum ValidatorKindParseError {
    /// Validator kind is not known or is gated behind a disabled feature.
    #[error("unsupported validator: {kind}")]
    UnsupportedValidator {
        /// Unsupported validator kind.
        kind: String,
    },
}

/// Closed set of validator implementations used by validator-backed recognizers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ValidatorKind {
    /// Basic email shape validator.
    EmailRfc,
    /// Parser-backed E.164 phone validator.
    #[cfg(feature = "phone-parser")]
    E164Phone,
    /// Parser-backed national phone validator for a fixed region.
    #[cfg(feature = "phone-parser")]
    E164PhoneNational(Region),
    /// Parser-backed international and national phone validity across supported regions.
    /// National values retain their original form rather than guessing a country code.
    #[cfg(feature = "phone-parser")]
    PhoneNumber,
    /// Luhn checksum validator.
    Luhn,
    /// IBAN MOD-97 validator.
    IbanMod97,
    /// Strict decimal dotted-quad IPv4 parser.
    Ipv4Parse,
    /// RFC 4291 / RFC 5952 IPv6 textual parser.
    Ipv6Parse,
    /// IPv4 parser that excludes RFC 5737 documentation ranges.
    Ipv4ParseNonDocumentation,
    /// IPv6 parser that excludes RFC 3849 and embedded RFC 5737 ranges.
    Ipv6ParseNonDocumentation,
    /// EIP-55 Ethereum address checksum validator.
    EthEip55,
    /// Indian Aadhaar Verhoeff checksum validator.
    AadhaarVerhoeff,
    /// French NIR MOD-97 key validator.
    FrNirMod97,
    /// German Steuer-ID MOD 11,10 checksum validator.
    DeSteuerIdMod1110,
    /// Dutch BSN MOD-11 checksum validator.
    BsnMod11,
    /// Brazilian CPF MOD-11 checksum validator.
    CpfMod11,
    /// Brazilian CNPJ MOD-11 checksum validator.
    CnpjMod11,
    /// UK NHS number MOD-11 checksum validator.
    UkNhsMod11,
}

/// Regions supported by national phone validators.
#[cfg(feature = "phone-parser")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Region {
    /// Germany.
    De,
    /// United States.
    Us,
    /// Austria.
    At,
    /// Switzerland.
    Ch,
    /// United Kingdom.
    Gb,
    /// Ireland.
    Ie,
    /// Australia.
    Au,
    /// Canada.
    Ca,
    /// New Zealand.
    Nz,
    /// South Africa.
    Za,
    /// France.
    Fr,
}

/// What validator veto does with a candidate whose validator fails.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum ValidatorOnFail {
    /// Drop the candidate and log it as a loser decided by `ConflictTier::ValidatorVeto`.
    #[default]
    Veto,
    /// Keep the candidate, write the failure on its audit row and never let the repeat-value
    /// sweep spread its value. Only [`ValidatorKind::allows_recorded_failure`] kinds take it.
    Record,
}

impl ValidatorOnFail {
    /// Parses a rulepack `on_fail` value (`veto` or `record`).
    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "veto" => Some(Self::Veto),
            "record" => Some(Self::Record),
            _ => None,
        }
    }
}

impl ValidatorKind {
    /// Whether this validator checks phone values, including regional national forms.
    pub fn is_phone(self) -> bool {
        #[cfg(feature = "phone-parser")]
        {
            matches!(
                self,
                Self::E164Phone | Self::E164PhoneNational(_) | Self::PhoneNumber
            )
        }
        #[cfg(not(feature = "phone-parser"))]
        {
            false
        }
    }

    /// Whether a failed validation may keep a candidate with its failure reason.
    /// Rulepacks opt in per recognizer; broad scanners must still veto.
    pub fn allows_recorded_failure(self) -> bool {
        matches!(
            self,
            Self::Luhn
                | Self::IbanMod97
                | Self::DeSteuerIdMod1110
                | Self::BsnMod11
                | Self::CpfMod11
                | Self::UkNhsMod11
        ) || {
            #[cfg(feature = "phone-parser")]
            {
                matches!(
                    self,
                    Self::E164Phone | Self::PhoneNumber | Self::E164PhoneNational(Region::Us)
                )
            }
            #[cfg(not(feature = "phone-parser"))]
            {
                false
            }
        }
    }

    /// Parses a policy validator kind.
    pub fn parse(s: &str) -> Result<Self, ValidatorKindParseError> {
        match s {
            "email_rfc" => Ok(Self::EmailRfc),
            #[cfg(feature = "phone-parser")]
            "e164_phone" => Ok(Self::E164Phone),
            #[cfg(feature = "phone-parser")]
            "phone_number" => Ok(Self::PhoneNumber),
            #[cfg(feature = "phone-parser")]
            "e164_phone_national_de" => Ok(Self::E164PhoneNational(Region::De)),
            #[cfg(feature = "phone-parser")]
            "e164_phone_national_us" => Ok(Self::E164PhoneNational(Region::Us)),
            "luhn" => Ok(Self::Luhn),
            "iban_mod97" => Ok(Self::IbanMod97),
            "ipv4_parse" => Ok(Self::Ipv4Parse),
            "ipv6_parse" => Ok(Self::Ipv6Parse),
            "ipv4_parse_non_documentation" => Ok(Self::Ipv4ParseNonDocumentation),
            "ipv6_parse_non_documentation" => Ok(Self::Ipv6ParseNonDocumentation),
            "eth_eip55" => Ok(Self::EthEip55),
            "aadhaar_verhoeff" => Ok(Self::AadhaarVerhoeff),
            "fr_nir_mod97" => Ok(Self::FrNirMod97),
            "de_steuer_id_mod1110" => Ok(Self::DeSteuerIdMod1110),
            "bsn_mod11" => Ok(Self::BsnMod11),
            "cpf_mod11" => Ok(Self::CpfMod11),
            "cnpj_mod11" => Ok(Self::CnpjMod11),
            "uk_nhs_mod11" => Ok(Self::UkNhsMod11),
            other => Err(ValidatorKindParseError::UnsupportedValidator {
                kind: other.to_string(),
            }),
        }
    }

    /// Returns whether the validator accepts the input.
    pub fn validates(self, input: &str) -> bool {
        match self {
            Self::AadhaarVerhoeff => aadhaar_verhoeff_check(input),
            Self::FrNirMod97 => fr_nir_mod97_check(input),
            Self::DeSteuerIdMod1110 => de_steuer_id_mod1110_check(input),
            Self::BsnMod11 => bsn_mod11_check(input),
            Self::CpfMod11 => cpf_mod11_check(input),
            Self::CnpjMod11 => cnpj_mod11_check(input),
            Self::UkNhsMod11 => uk_nhs_mod11_check(input),
            _ => self.canonical_form(input).is_some(),
        }
    }

    /// Applies validation and returns a typed outcome for audit.
    pub fn validate(self, input: &str) -> ValidatorOutcome {
        match self.canonical_form(input) {
            Some(canonical_form) => ValidatorOutcome::Pass {
                canonical_form: Some(canonical_form),
            },
            None => ValidatorOutcome::Fail {
                reason: match self {
                    #[cfg(feature = "phone-parser")]
                    Self::PhoneNumber if input.starts_with('+') || input.starts_with("00") => {
                        ValidatorFailReason::PhoneE164Rejected
                    }
                    Self::Ipv4ParseNonDocumentation => match input.parse() {
                        Ok(address) if ipv4_is_documentation(address) => {
                            ValidatorFailReason::Ipv4DocumentationRange
                        }
                        Ok(_) => ValidatorFailReason::Ipv4LoopbackRange,
                        Err(_) => self.fail_reason(),
                    },
                    Self::Ipv6ParseNonDocumentation => match input.parse() {
                        Ok(address) if ipv6_is_documentation(address) => {
                            ValidatorFailReason::Ipv6DocumentationRange
                        }
                        Ok(_) => ValidatorFailReason::Ipv6LoopbackRange,
                        Err(_) => self.fail_reason(),
                    },
                    _ => self.fail_reason(),
                },
            },
        }
    }

    /// Returns the canonical form for accepted input.
    pub fn canonical_form(self, input: &str) -> Option<String> {
        match self {
            Self::EmailRfc => is_basic_email(input).then(|| input.to_string()),
            #[cfg(feature = "phone-parser")]
            Self::E164Phone => e164_phone_check(input).then(|| input.to_string()),
            #[cfg(feature = "phone-parser")]
            Self::E164PhoneNational(region) => validate_phone_national(region, input),
            #[cfg(feature = "phone-parser")]
            Self::PhoneNumber => phone_number_check(input).then(|| input.to_string()),
            Self::Luhn => luhn_check(input).then(|| input.to_string()),
            Self::IbanMod97 => iban_mod97_check(input).then(|| input.to_string()),
            Self::Ipv4Parse => ipv4_parse_check(input).then(|| input.to_string()),
            Self::Ipv6Parse => ipv6_parse_check(input).then(|| input.to_string()),
            Self::Ipv4ParseNonDocumentation => input
                .parse::<std::net::Ipv4Addr>()
                .ok()
                .filter(|address| !ipv4_is_documentation(*address) && !address.is_loopback())
                .map(|_| input.to_string()),
            Self::Ipv6ParseNonDocumentation => input
                .parse::<std::net::Ipv6Addr>()
                .ok()
                .filter(|address| !ipv6_is_documentation(*address) && !ipv6_is_loopback(*address))
                .map(|_| input.to_string()),
            Self::EthEip55 => eth_eip55_check(input).then(|| input.to_string()),
            Self::AadhaarVerhoeff => {
                canonical_ascii_digits::<12>(input).filter(|_| aadhaar_verhoeff_check(input))
            }
            Self::FrNirMod97 => {
                canonical_ascii_digits::<15>(input).filter(|_| fr_nir_mod97_check(input))
            }
            Self::DeSteuerIdMod1110 => {
                canonical_ascii_digits::<11>(input).filter(|_| de_steuer_id_mod1110_check(input))
            }
            Self::BsnMod11 => canonical_ascii_digits::<9>(input).filter(|_| bsn_mod11_check(input)),
            Self::CpfMod11 => {
                canonical_ascii_digits::<11>(input).filter(|_| cpf_mod11_check(input))
            }
            Self::CnpjMod11 => {
                canonical_ascii_digits::<14>(input).filter(|_| cnpj_mod11_check(input))
            }
            Self::UkNhsMod11 => {
                canonical_ascii_digits::<10>(input).filter(|_| uk_nhs_mod11_check(input))
            }
        }
    }

    /// Returns the ordinary parse or checksum failure reason. Input-dependent
    /// exclusions report their own reason through [`Self::validate`].
    pub fn fail_reason(self) -> ValidatorFailReason {
        match self {
            Self::EmailRfc => ValidatorFailReason::EmailRfcRejected,
            #[cfg(feature = "phone-parser")]
            Self::E164Phone => ValidatorFailReason::PhoneE164Rejected,
            #[cfg(feature = "phone-parser")]
            Self::PhoneNumber => ValidatorFailReason::PhoneNationalRegionMismatch,
            #[cfg(feature = "phone-parser")]
            Self::E164PhoneNational(_) => ValidatorFailReason::PhoneNationalRegionMismatch,
            Self::Luhn => ValidatorFailReason::LuhnFailed,
            Self::IbanMod97 => ValidatorFailReason::IbanMod97Failed,
            Self::Ipv4Parse => ValidatorFailReason::Ipv4ParseFailed,
            Self::Ipv6Parse => ValidatorFailReason::Ipv6ParseFailed,
            Self::Ipv4ParseNonDocumentation => ValidatorFailReason::Ipv4ParseFailed,
            Self::Ipv6ParseNonDocumentation => ValidatorFailReason::Ipv6ParseFailed,
            Self::EthEip55 => ValidatorFailReason::EthEip55ChecksumFailed,
            Self::AadhaarVerhoeff => ValidatorFailReason::AadhaarVerhoeffFailed,
            Self::FrNirMod97 => ValidatorFailReason::FrNirMod97Failed,
            Self::DeSteuerIdMod1110 => ValidatorFailReason::DeSteuerIdMod1110Failed,
            Self::BsnMod11 => ValidatorFailReason::BsnMod11Failed,
            Self::CpfMod11 => ValidatorFailReason::CpfMod11Failed,
            Self::CnpjMod11 => ValidatorFailReason::CnpjMod11Failed,
            Self::UkNhsMod11 => ValidatorFailReason::UkNhsMod11Failed,
        }
    }
}

fn is_basic_email(input: &str) -> bool {
    let Some((local, domain)) = input.split_once('@') else {
        return false;
    };
    !local.is_empty() && domain.contains('.') && !domain.starts_with('.') && !domain.ends_with('.')
}

#[cfg(feature = "phone-parser")]
fn e164_phone_check(input: &str) -> bool {
    phonenumber::parse(None, input).is_ok_and(|phone| phonenumber::is_valid(&phone))
}

/// International dialing prefixes and optional trunk markers are display syntax.
#[cfg(feature = "phone-parser")]
fn phone_number_check(input: &str) -> bool {
    let normalized = input.strip_prefix("00").map(|tail| format!("+{tail}"));
    let value = normalized.as_deref().unwrap_or(input);
    if value.starts_with('+') {
        return phonenumber::parse(None, value).is_ok_and(|phone| {
            // Some national plans accept longer subscriber numbers. They cannot be
            // trusted as international values beyond E.164's 15-digit limit.
            // ITU-T E.164 Annex A.3.1.1: https://www.itu.int/rec/T-REC-E.164-202602-I/en
            if phone
                .format()
                .mode(phonenumber::Mode::E164)
                .to_string()
                .bytes()
                .filter(u8::is_ascii_digit)
                .count()
                > 15
            {
                return false;
            }
            phone.is_valid()
                || (phone.country().code() == 44
                    // The reserved-block exception must not bless a per-digit slash run
                    // that the parser rejected; recorded failures cannot seed repeats.
                    && value.bytes().filter(|byte| *byte == b'/').count() <= 1
                    && is_safe_fixture_phone(
                        Region::Gb,
                        &phone.format().mode(phonenumber::Mode::E164).to_string(),
                    ))
        });
    }
    [
        Region::De,
        Region::Us,
        Region::At,
        Region::Ch,
        Region::Gb,
        Region::Ie,
        Region::Au,
        Region::Ca,
        Region::Nz,
        Region::Za,
        Region::Fr,
    ]
    .into_iter()
    .any(|region| validate_phone_national(region, value).is_some())
}

#[cfg(feature = "phone-parser")]
fn validate_phone_national(region: Region, input: &str) -> Option<String> {
    let country = match region {
        Region::De => phonenumber::country::DE,
        Region::Us => phonenumber::country::US,
        Region::At => phonenumber::country::AT,
        Region::Ch => phonenumber::country::CH,
        Region::Gb => phonenumber::country::GB,
        Region::Ie => phonenumber::country::IE,
        Region::Au => phonenumber::country::AU,
        Region::Ca => phonenumber::country::CA,
        Region::Nz => phonenumber::country::NZ,
        Region::Za => phonenumber::country::ZA,
        Region::Fr => phonenumber::country::FR,
    };
    let expected_code = match region {
        Region::De => 49,
        Region::Us | Region::Ca => 1,
        Region::At => 43,
        Region::Ch => 41,
        Region::Gb => 44,
        Region::Ie => 353,
        Region::Au => 61,
        Region::Nz => 64,
        Region::Za => 27,
        Region::Fr => 33,
    };
    let number = phonenumber::parse(Some(country), input).ok()?;
    if number.country().code() != expected_code {
        return None;
    }
    if number.is_valid() || is_safe_fixture_phone(region, input) {
        return Some(number.format().mode(phonenumber::Mode::E164).to_string());
    }
    None
}

#[cfg(feature = "phone-parser")]
fn is_safe_fixture_phone(region: Region, input: &str) -> bool {
    let digits = input
        .chars()
        .filter(char::is_ascii_digit)
        .collect::<String>();
    match region {
        Region::Us => {
            digits == "15550100"
                || matches!(digits.strip_prefix('1'), Some(rest) if rest.len() == 10 && rest[3..].starts_with("55501"))
        }
        // Ofcom reserves the entire mobile drama block; libphonenumber deliberately
        // excludes this allocation, but it remains the phone shape adopters use in tests.
        // https://www.ofcom.org.uk/phones-and-broadband/phone-numbers/numbers-for-drama
        Region::Gb => {
            if input.bytes().filter(|byte| *byte == b'/').count() > 1 {
                return false;
            }
            let national = digits
                .strip_prefix("44")
                .or_else(|| digits.strip_prefix('0'))
                .unwrap_or(&digits);
            national.len() == 10 && national.starts_with("7700900")
        }
        Region::De => matches!(
            digits.as_str(),
            "493000000000"
                | "4915100000000"
                | "4915550112233"
                | "015550112233"
                | "491710000000"
                | "01710000000"
        ),
        _ => false,
    }
}

/// The one Luhn check: the `luhn` validator and [`payment_card::scan_card_run`] both call it.
/// It checks the ASCII digits. Whitespace (any Unicode `White_Space`, as the card patterns'
/// `\s`), `-` and non-ASCII digits (which the card patterns' `\d` matches but no card number is
/// written in) are skipped; any other character fails the check, and so does an ASCII digit count
/// outside 13 to 19 or an all-zero number. Fullwidth digits reach it already folded to ASCII by
/// normalization.
pub(crate) fn luhn_check(input: &str) -> bool {
    let mut digits = Vec::new();
    for ch in input.chars() {
        if ch.is_whitespace() || ch == '-' || (ch.is_numeric() && !ch.is_ascii_digit()) {
            continue;
        }
        if !ch.is_ascii_digit() {
            return false;
        }
        digits.push(ch as u8 - b'0');
    }
    if !(13..=19).contains(&digits.len()) || digits.iter().all(|digit| *digit == 0) {
        return false;
    }

    let sum: u32 = digits
        .iter()
        .rev()
        .enumerate()
        .map(|(index, digit)| {
            let mut value = u32::from(*digit);
            if index % 2 == 1 {
                value *= 2;
                if value > 9 {
                    value -= 9;
                }
            }
            value
        })
        .sum();
    sum.is_multiple_of(10)
}

fn iban_mod97_check(input: &str) -> bool {
    let canonical = iban_canonicalize(input);
    let bytes = canonical.as_bytes();
    if bytes.len() < 4 {
        return false;
    }
    if !bytes[0].is_ascii_uppercase()
        || !bytes[1].is_ascii_uppercase()
        || !bytes[2].is_ascii_digit()
        || !bytes[3].is_ascii_digit()
    {
        return false;
    }
    let Some(expected_len) = iban_country_length(&bytes[..2]) else {
        return false;
    };
    if bytes.len() != expected_len {
        return false;
    }
    if !bytes.iter().all(u8::is_ascii_alphanumeric) {
        return false;
    }

    let mut remainder = 0u32;
    for byte in bytes[4..].iter().chain(bytes[..4].iter()).copied() {
        match byte {
            b'0'..=b'9' => {
                remainder = (remainder * 10 + u32::from(byte - b'0')) % 97;
            }
            b'A'..=b'Z' => {
                let value = u32::from(byte - b'A') + 10;
                remainder = (remainder * 10 + value / 10) % 97;
                remainder = (remainder * 10 + value % 10) % 97;
            }
            _ => return false,
        }
    }
    remainder == 1
}

/// Canonical IBAN length for an ISO 3166-1 alpha-2 country code, or `None` when
/// the country is not in the ISO 13616 IBAN Registry.
///
/// This is the one source of truth for IBAN length in the workspace. The
/// `iban_mod97` validator gates candidates on it, and the `iban.structural`
/// pattern in the bundled `core` rulepack carries one alternation branch per
/// registry length so a candidate span stops at the country's real IBAN length
/// instead of borrowing the following word. The two are held
/// in agreement by a drift test in `gaze-recognizers`, which is why this needs
/// to be reachable from outside the crate.
#[must_use]
pub fn iban_registry_length(country: &str) -> Option<usize> {
    iban_country_length(country.as_bytes())
}

fn iban_country_length(country: &[u8]) -> Option<usize> {
    // ISO 13616 IBAN Registry country lengths. MOD-97 alone has a false-accept
    // rate near 1/97, so exact country length gates candidates before checksum.
    match country {
        b"AD" => Some(24),
        b"AE" => Some(23),
        b"AL" => Some(28),
        b"AT" => Some(20),
        b"AZ" => Some(28),
        b"BA" => Some(20),
        b"BE" => Some(16),
        b"BG" => Some(22),
        b"BH" => Some(22),
        b"BI" => Some(27),
        b"BR" => Some(29),
        b"BY" => Some(28),
        b"CH" => Some(21),
        b"CR" => Some(22),
        b"CY" => Some(28),
        b"CZ" => Some(24),
        b"DE" => Some(22),
        b"DJ" => Some(27),
        b"DK" => Some(18),
        b"DO" => Some(28),
        b"EE" => Some(20),
        b"EG" => Some(29),
        b"ES" => Some(24),
        b"FI" => Some(18),
        b"FK" => Some(18),
        b"FO" => Some(18),
        b"FR" => Some(27),
        b"GB" => Some(22),
        b"GE" => Some(22),
        b"GI" => Some(23),
        b"GL" => Some(18),
        b"GR" => Some(27),
        b"GT" => Some(28),
        b"HN" => Some(28),
        b"HR" => Some(21),
        b"HU" => Some(28),
        b"IE" => Some(22),
        b"IL" => Some(23),
        b"IQ" => Some(23),
        b"IS" => Some(26),
        b"IT" => Some(27),
        b"JO" => Some(30),
        b"KW" => Some(30),
        b"KZ" => Some(20),
        b"LB" => Some(28),
        b"LC" => Some(32),
        b"LI" => Some(21),
        b"LT" => Some(20),
        b"LU" => Some(20),
        b"LV" => Some(21),
        b"LY" => Some(25),
        b"MC" => Some(27),
        b"MD" => Some(24),
        b"ME" => Some(22),
        b"MK" => Some(19),
        b"MN" => Some(20),
        b"MR" => Some(27),
        b"MT" => Some(31),
        b"MU" => Some(30),
        b"NI" => Some(28),
        b"NL" => Some(18),
        b"NO" => Some(15),
        b"OM" => Some(23),
        b"PK" => Some(24),
        b"PL" => Some(28),
        b"PS" => Some(29),
        b"PT" => Some(25),
        b"QA" => Some(29),
        b"RO" => Some(24),
        b"RS" => Some(22),
        b"RU" => Some(33),
        b"SA" => Some(24),
        b"SC" => Some(31),
        b"SD" => Some(18),
        b"SE" => Some(24),
        b"SI" => Some(19),
        b"SK" => Some(24),
        b"SM" => Some(27),
        b"SO" => Some(23),
        b"ST" => Some(25),
        b"SV" => Some(28),
        b"TL" => Some(23),
        b"TN" => Some(24),
        b"TR" => Some(26),
        b"UA" => Some(29),
        b"VA" => Some(22),
        b"VG" => Some(24),
        b"XK" => Some(20),
        b"YE" => Some(30),
        _ => None,
    }
}

fn iban_canonicalize(input: &str) -> String {
    input
        .chars()
        .filter(|ch| !ch.is_ascii_whitespace())
        .flat_map(char::to_uppercase)
        .collect()
}

fn ipv4_parse_check(input: &str) -> bool {
    input.parse::<std::net::Ipv4Addr>().is_ok()
}

fn ipv6_parse_check(input: &str) -> bool {
    input.parse::<std::net::Ipv6Addr>().is_ok()
}

fn ipv4_is_documentation(address: std::net::Ipv4Addr) -> bool {
    let [a, b, c, _] = address.octets();
    matches!((a, b, c), (192, 0, 2) | (198, 51, 100) | (203, 0, 113))
}

fn ipv6_is_documentation(address: std::net::Ipv6Addr) -> bool {
    let segments = address.segments();
    (segments[0] == 0x2001 && segments[1] == 0x0db8)
        || address.to_ipv4().is_some_and(ipv4_is_documentation)
}

/// `::1`, or an IPv4-mapped (`::ffff:127.0.0.1`) or IPv4-compatible (`::127.0.0.1`) loopback. A loopback
/// address never leaves the host, so it identifies no person or device.
fn ipv6_is_loopback(address: std::net::Ipv6Addr) -> bool {
    address.is_loopback() || address.to_ipv4().is_some_and(|v4| v4.is_loopback())
}

fn eth_eip55_check(input: &str) -> bool {
    let Some(address) = input.strip_prefix("0x") else {
        return false;
    };
    if address.len() != 40 || !address.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        return false;
    }
    if address
        .bytes()
        .all(|byte| !byte.is_ascii_alphabetic() || byte.is_ascii_lowercase())
        || address
            .bytes()
            .all(|byte| !byte.is_ascii_alphabetic() || byte.is_ascii_uppercase())
    {
        return true;
    }

    let lowercase = address.to_ascii_lowercase();
    let hash = Keccak256::digest(lowercase.as_bytes());
    for (index, byte) in address.bytes().enumerate() {
        if byte.is_ascii_digit() {
            continue;
        }
        let hash_nibble = if index % 2 == 0 {
            hash[index / 2] >> 4
        } else {
            hash[index / 2] & 0x0f
        };
        if (hash_nibble > 7) != byte.is_ascii_uppercase() {
            return false;
        }
    }
    true
}

fn collect_ascii_digits<const N: usize>(input: &str) -> Option<[u8; N]> {
    let mut digits = [0u8; N];
    let mut count = 0usize;
    for byte in input.bytes() {
        if byte.is_ascii_digit() {
            if count == N {
                return None;
            }
            digits[count] = byte - b'0';
            count += 1;
        } else if matches!(byte, b' ' | b'\t' | b'\n' | b'\r' | b'-' | b'.' | b'/') {
            continue;
        } else {
            return None;
        }
    }
    (count == N).then_some(digits)
}

fn canonical_ascii_digits<const N: usize>(input: &str) -> Option<String> {
    let digits = collect_ascii_digits::<N>(input)?;
    let mut canonical = String::with_capacity(N);
    for digit in digits {
        canonical.push(char::from(b'0' + digit));
    }
    Some(canonical)
}

fn not_all_same<const N: usize>(digits: &[u8; N]) -> bool {
    digits[1..].iter().any(|digit| *digit != digits[0])
}

fn aadhaar_verhoeff_check(input: &str) -> bool {
    const D: [[u8; 10]; 10] = [
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
        [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
        [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
        [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
        [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
        [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
        [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
        [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
        [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
        [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
    ];
    const P: [[u8; 10]; 8] = [
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
        [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
        [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
        [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
        [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
        [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
        [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
        [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
    ];
    let Some(digits) = collect_ascii_digits::<12>(input) else {
        return false;
    };
    if digits[0] < 2 || !not_all_same(&digits) {
        return false;
    }
    let mut checksum = 0u8;
    for (index, digit) in digits.iter().rev().enumerate() {
        checksum = D[checksum as usize][P[index % 8][*digit as usize] as usize];
    }
    checksum == 0
}

fn fr_nir_mod97_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<15>(input) else {
        return false;
    };
    if !matches!(digits[0], 1 | 2 | 3 | 4 | 7 | 8) {
        return false;
    }
    let month = digits[3] * 10 + digits[4];
    if !(1..=12).contains(&month) && !(20..=42).contains(&month) && !(50..=99).contains(&month) {
        return false;
    }
    let mut number = 0u32;
    for digit in &digits[..13] {
        number = (number * 10 + u32::from(*digit)) % 97;
    }
    let key = u32::from(digits[13]) * 10 + u32::from(digits[14]);
    97 - number == key
}

fn de_steuer_id_mod1110_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<11>(input) else {
        return false;
    };
    if !steuer_id_first_ten_digits_valid(&digits) {
        return false;
    }
    let mut product = 10u8;
    for digit in &digits[..10] {
        let mut sum = (*digit + product) % 10;
        if sum == 0 {
            sum = 10;
        }
        product = (2 * sum) % 11;
    }
    let check = (11 - product) % 10;
    check == digits[10]
}

fn steuer_id_first_ten_digits_valid(digits: &[u8; 11]) -> bool {
    if digits[0] == 0 {
        return false;
    }
    let mut counts = [0u8; 10];
    for digit in &digits[..10] {
        counts[*digit as usize] += 1;
    }
    let repeated_digits = counts.iter().filter(|count| **count > 1).count();
    let missing_digits = counts.iter().filter(|count| **count == 0).count();
    let repeated_count_valid = counts.iter().any(|count| matches!(*count, 2 | 3));
    repeated_digits == 1 && repeated_count_valid && matches!(missing_digits, 1 | 2)
}

fn bsn_mod11_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<9>(input) else {
        return false;
    };
    if !not_all_same(&digits) {
        return false;
    }
    let sum: i32 = digits[..8]
        .iter()
        .enumerate()
        .map(|(index, digit)| i32::from(*digit) * (9 - index as i32))
        .sum::<i32>()
        - i32::from(digits[8]);
    sum.rem_euclid(11) == 0
}

fn cpf_mod11_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<11>(input) else {
        return false;
    };
    if !not_all_same(&digits) {
        return false;
    }
    mod11_check_digit(&digits[..9], 10) == digits[9]
        && mod11_check_digit(&digits[..10], 11) == digits[10]
}

fn cnpj_mod11_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<14>(input) else {
        return false;
    };
    if !not_all_same(&digits) {
        return false;
    }
    const FIRST: [u8; 12] = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
    const SECOND: [u8; 13] = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
    weighted_mod11_check_digit(&digits[..12], &FIRST) == digits[12]
        && weighted_mod11_check_digit(&digits[..13], &SECOND) == digits[13]
}

fn uk_nhs_mod11_check(input: &str) -> bool {
    let Some(digits) = collect_ascii_digits::<10>(input) else {
        return false;
    };
    if !not_all_same(&digits) {
        return false;
    }
    let sum: u32 = digits[..9]
        .iter()
        .enumerate()
        .map(|(index, digit)| u32::from(*digit) * (10 - index as u32))
        .sum();
    let check = 11 - (sum % 11);
    let check = if check == 11 { 0 } else { check };
    check != 10 && check == u32::from(digits[9])
}

fn mod11_check_digit(digits: &[u8], start_weight: u8) -> u8 {
    let weights = (2..=start_weight).rev();
    let sum: u32 = digits
        .iter()
        .zip(weights)
        .map(|(digit, weight)| u32::from(*digit) * u32::from(weight))
        .sum();
    let remainder = sum % 11;
    if remainder < 2 {
        0
    } else {
        (11 - remainder) as u8
    }
}

fn weighted_mod11_check_digit(digits: &[u8], weights: &[u8]) -> u8 {
    let sum: u32 = digits
        .iter()
        .zip(weights)
        .map(|(digit, weight)| u32::from(*digit) * u32::from(*weight))
        .sum();
    let remainder = sum % 11;
    if remainder < 2 {
        0
    } else {
        (11 - remainder) as u8
    }
}

/// A detected span and its class/source metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct Detection {
    /// Byte span in the original input.
    pub span: Range<usize>,
    /// PII class assigned to the span.
    pub class: PiiClass,
    /// Detector source identifier.
    pub source: String,
}

impl Detection {
    /// Builds a detected PII span.
    pub fn new(span: Range<usize>, class: PiiClass, source: impl Into<String>) -> Self {
        Self {
            span,
            class,
            source: source.into(),
        }
    }
}

/// Observer-only post-clean check (Pass 3 in the detection pipeline).
///
/// Runs against already-tokenized output. May report suspected missed PII via
/// [`LeakReport`] but **must not** mutate the token manifest, the `CleanDocument`,
/// or the restore path. Safety nets are additive defense-in-depth, not a replacement
/// for Pass 1/2 detection.
///
/// Activate at runtime with `Pipeline::with_safety_net` (post-build) or
/// `PipelineBuilder::register_safety_net` (during build), or via the CLI
/// `--safety-net=<name>` flag.
///
/// If a safety net reports a suspected miss, the caller decides the response; the
/// pipeline never silently re-cleans based on safety net output.
pub trait SafetyNet: Send + Sync {
    /// Stable backend identifier used in telemetry and audit rows.
    fn id(&self) -> &str;

    /// Locale tags supported by this safety net. Empty means global.
    fn supported_locales(&self) -> &[LocaleTag];

    /// Checks clean text for possible PII that the manifest did not cover.
    fn check(
        &self,
        clean_text: &str,
        context: SafetyNetContext<'_>,
    ) -> Result<Vec<LeakSuspect>, SafetyNetError>;

    /// Checks a second, byte-aligned view when the backend supports it.
    /// Other safety nets keep their existing single-view behavior.
    fn check_with_neutral(
        &self,
        stable_text: &str,
        _neutral_text: Option<&str>,
        context: SafetyNetContext<'_>,
    ) -> Result<Vec<LeakSuspect>, SafetyNetError> {
        self.check(stable_text, context)
    }

    /// Checks byte-aligned views and returns bytes-free refusal telemetry.
    /// Backends that use a neutral view override this to retain both views.
    fn check_with_neutral_and_telemetry(
        &self,
        stable_text: &str,
        _neutral_text: Option<&str>,
        context: SafetyNetContext<'_>,
    ) -> Result<(Vec<LeakSuspect>, Vec<LeakReportTelemetry>), SafetyNetError> {
        self.check_with_telemetry(stable_text, context)
    }

    /// Checks text and returns metadata for spans deliberately refused by the backend.
    /// Existing implementations keep their suspect-only behavior.
    fn check_with_telemetry(
        &self,
        clean_text: &str,
        context: SafetyNetContext<'_>,
    ) -> Result<(Vec<LeakSuspect>, Vec<LeakReportTelemetry>), SafetyNetError> {
        self.check(clean_text, context)
            .map(|suspects| (suspects, Vec::new()))
    }
}

/// Context passed to a privacy safety net.
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub struct SafetyNetContext<'a> {
    /// Optional caller-supplied dictionaries. `new` leaves this unset; pipeline
    /// wrappers supply the caller bundle or `Some(empty default)`. Locale-aware
    /// model backends have their separate text/locale interface without dictionaries.
    pub dictionaries: Option<&'a DictionaryBundle>,
    /// Tokens emitted by the pipeline or verified as owned at a strict boundary.
    /// At that boundary, raw spans use expanded-owner input coordinates, not
    /// offsets into the literal token-bearing input. Do not index that literal
    /// input with reconstructed raw spans.
    pub manifest: &'a Manifest,
    /// Active session-level locale chain. For `RawDocument::Structured`, locale
    /// gating uses this same session-level chain across all fields; structured
    /// fields do not carry per-field locale annotations.
    pub locale_chain: &'a [LocaleTag],
    /// Source document kind being checked.
    pub document_kind: DocumentKind,
    /// Optional audit session identifier.
    pub session_id: Option<&'a str>,
    /// Structured-document field path, such as `$.user.email`.
    pub field_path: Option<&'a str>,
}

impl<'a> SafetyNetContext<'a> {
    /// Supplies the same dictionary bundle used by primary detection.
    pub fn with_dictionaries(mut self, dictionaries: &'a DictionaryBundle) -> Self {
        self.dictionaries = Some(dictionaries);
        self
    }

    /// Builds safety-net context for one clean text segment.
    pub fn new(
        manifest: &'a Manifest,
        locale_chain: &'a [LocaleTag],
        document_kind: DocumentKind,
        session_id: Option<&'a str>,
        field_path: Option<&'a str>,
    ) -> Self {
        Self {
            dictionaries: None,
            manifest,
            locale_chain,
            document_kind,
            session_id,
            field_path,
        }
    }
}

/// What a replacement covers: a whole recognized selection, or a residual
/// fragment of the admitted raw union that whole-candidate arbitration dropped.
///
/// This is the distinction a consumer needs before it may treat a replacement as
/// an entity. A fragment is a real protected byte range, but it is *not* an
/// entity: it can be a single space, quote or letter carved out of the middle of
/// one. Indexing or counting it as an entity produces a falsehood.
///
/// Serialization is backward compatible in both directions. `Whole` is the
/// default and is omitted from output, so JSON written for existing whole-value
/// spans stays byte-identical, and JSON written before this field existed
/// deserializes as `Whole`.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum EmittedTokenOrigin {
    /// Covers a whole selection chosen by conflict resolution.
    #[default]
    Whole,
    /// Covers raw bytes that admitted originals evidenced but no selection kept.
    ResidualFragment,
}

impl EmittedTokenOrigin {
    /// Whether this replacement covers a whole selection.
    pub fn is_whole(&self) -> bool {
        matches!(self, Self::Whole)
    }

    /// Whether this replacement covers a residual fragment.
    pub fn is_residual_fragment(&self) -> bool {
        matches!(self, Self::ResidualFragment)
    }
}

/// A replacement emitted by the pseudonymization pipeline.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct EmittedTokenSpan {
    /// Byte span in the clean text.
    pub clean_span: Range<usize>,
    /// Byte span in the raw text that produced the token.
    pub raw_span: Range<usize>,
    /// PII class represented by the emitted token.
    pub class: PiiClass,
    /// Whether this replacement covers a whole selection or a residual fragment.
    #[serde(default, skip_serializing_if = "EmittedTokenOrigin::is_whole")]
    pub origin: EmittedTokenOrigin,
}

impl EmittedTokenSpan {
    /// Builds an emitted token span covering a whole selection.
    pub fn new(clean_span: Range<usize>, raw_span: Range<usize>, class: PiiClass) -> Self {
        Self {
            clean_span,
            raw_span,
            class,
            origin: EmittedTokenOrigin::Whole,
        }
    }

    /// Builds an emitted token span covering a residual fragment.
    pub fn residual_fragment(
        clean_span: Range<usize>,
        raw_span: Range<usize>,
        class: PiiClass,
    ) -> Self {
        Self {
            clean_span,
            raw_span,
            class,
            origin: EmittedTokenOrigin::ResidualFragment,
        }
    }
}

/// Set of emitted token spans for one clean text segment.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Manifest {
    /// Spans sorted by `clean_span.start`.
    pub spans: Vec<EmittedTokenSpan>,
}

impl Manifest {
    /// Builds a manifest from spans and sorts them by clean byte start.
    pub fn from_spans(mut spans: Vec<EmittedTokenSpan>) -> Self {
        spans.sort_by_key(|span| (span.clean_span.start, span.clean_span.end));
        Self { spans }
    }

    /// Diffs one safety-net suspect span against emitted token coverage.
    ///
    /// Returns `None` when the suspect span is continuously covered by emitted
    /// token spans of the same class. Internal gaps return
    /// `LeakKind::PartialBleed`. When multiple uncovered gaps exist, this method
    /// deterministically returns the first gap by byte offset; full gap
    /// enumeration is intentionally deferred to a future report format.
    pub fn diff_against(
        &self,
        suspect_span: &Range<usize>,
        suspect_class: &PiiClass,
    ) -> Option<LeakKind> {
        if suspect_span.is_empty() {
            return None;
        }

        let start_idx = self
            .spans
            .partition_point(|span| span.clean_span.end <= suspect_span.start);
        let overlapping = self.spans[start_idx..]
            .iter()
            .take_while(|span| span.clean_span.start < suspect_span.end)
            .filter(|span| ranges_overlap(&span.clean_span, suspect_span))
            .collect::<Vec<_>>();

        if overlapping.is_empty() {
            return Some(LeakKind::Uncovered);
        }

        let mut cursor = suspect_span.start;
        let mut first_mismatch = None::<&EmittedTokenSpan>;
        for span in overlapping {
            if span.clean_span.start > cursor {
                return Some(LeakKind::PartialBleed {
                    uncovered: cursor..span.clean_span.start.min(suspect_span.end),
                });
            }

            if span.clean_span.end > cursor {
                if first_mismatch.is_none() && &span.class != suspect_class {
                    first_mismatch = Some(span);
                }
                cursor = cursor.max(span.clean_span.end.min(suspect_span.end));
                if cursor >= suspect_span.end {
                    break;
                }
            }
        }

        if cursor < suspect_span.end {
            return Some(LeakKind::PartialBleed {
                uncovered: cursor..suspect_span.end,
            });
        }

        first_mismatch.map(|span| LeakKind::ClassMismatch {
            pipeline_class: span.class.clone(),
            safety_net_class: suspect_class.clone(),
        })
    }
}

fn ranges_overlap(left: &Range<usize>, right: &Range<usize>) -> bool {
    left.start < right.end && right.start < left.end
}

/// Suspected leak reported by an observer-only safety net.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct LeakSuspect {
    /// Byte span in clean text.
    pub span: Range<usize>,
    /// Mapped PII class for the suspect.
    pub class: PiiClass,
    /// Safety-net backend identifier.
    pub safety_net_id: String,
    /// Optional backend confidence score.
    pub score: Option<f32>,
    /// Leak classification after manifest correlation.
    pub kind: LeakKind,
    /// Raw backend label after validation/mapping, never source text.
    pub raw_label: String,
    /// Optional structured field path.
    pub field_path: Option<String>,
}

impl LeakSuspect {
    /// Builds a safety-net leak suspect.
    pub fn new(
        span: Range<usize>,
        class: PiiClass,
        safety_net_id: impl Into<String>,
        score: Option<f32>,
        kind: LeakKind,
        raw_label: impl Into<String>,
        field_path: Option<String>,
    ) -> Self {
        Self {
            span,
            class,
            safety_net_id: safety_net_id.into(),
            score,
            kind,
            raw_label: raw_label.into(),
            field_path,
        }
    }
}

/// The category of a suspected missed PII span.
///
/// `LeakKind` is `#[non_exhaustive]`. Match with a wildcard for forward compatibility.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum LeakKind {
    /// No same-class emitted token overlaps the suspect span.
    Uncovered,
    /// The suspect is only partly covered; `uncovered` is the first gap.
    PartialBleed {
        /// First uncovered byte range in the suspect span.
        uncovered: Range<usize>,
    },
    /// The suspect is continuously covered, but by a different class.
    ClassMismatch {
        /// Class emitted by the pipeline.
        pipeline_class: PiiClass,
        /// Class reported by the safety net.
        safety_net_class: PiiClass,
    },
}

impl LeakKind {
    /// Returns the canonical audit-row spelling.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Uncovered => "uncovered",
            Self::PartialBleed { .. } => "partial_bleed",
            Self::ClassMismatch { .. } => "class_mismatch",
        }
    }
}

/// Bytes-free telemetry emitted by safety-net orchestration.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum LeakReportTelemetry {
    /// Safety net skipped because the session-level locale chain did not match.
    LocaleSkipped {
        /// Safety-net backend identifier.
        safety_net_id: String,
        /// Document kind checked.
        document_kind: DocumentKind,
        /// Optional structured field path when skip was recorded per field.
        field_path: Option<String>,
    },
    /// A word-like suspect (name, location, organization) whose action span starts or ends
    /// inside a word in the text it was reported on.
    ///
    /// The suspect is not tokenized and not deleted: acting on part of a word mangles the text
    /// the agent reads and protects nothing whole. It stays in the report's suspects; this row
    /// says why no stage acted on it. Offsets are in the text of the pass that reported it, so a
    /// re-run after earlier tokens shifted the text can add a row for the same sub-word.
    UnactionableSubword {
        /// Safety-net backend identifier.
        safety_net_id: String,
        /// Class the net reported.
        class: PiiClass,
        /// Byte span of the would-be action in the text the net checked.
        span: Range<usize>,
        /// Document kind checked.
        document_kind: DocumentKind,
        /// Optional structured field path of the suspect.
        field_path: Option<String>,
    },
    /// A validated model span rejected by a narrow, versioned context guard.
    ModelSpanRefused {
        /// Safety-net backend identifier.
        safety_net_id: String,
        /// Typed refusal reason, without source text.
        reason: SafetyNetRefusalReason,
        /// Byte span in clean text.
        span: Range<usize>,
        /// Document kind checked.
        document_kind: DocumentKind,
        /// Optional structured field path.
        field_path: Option<String>,
    },
}

/// Closed reasons for refusing a validated safety-net model span.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SafetyNetRefusalReason {
    /// Nym BUILDING_NUMBER on an ASCII-digit pagination/count field from key table v1.
    NymPaginationKeyV1,
}

impl SafetyNetRefusalReason {
    /// Stable metadata-only audit spelling.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::NymPaginationKeyV1 => "nym_pagination_key_v1",
        }
    }

    /// Raw model label and mapped class for a refused span's audit row.
    pub fn audit_labels(self) -> (&'static str, &'static str) {
        match self {
            Self::NymPaginationKeyV1 => ("BUILDING_NUMBER", "custom:building_number"),
        }
    }
}

/// Aggregate leak report statistics.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct LeakReportStats {
    /// Number of suspects reported.
    pub suspect_count: usize,
    /// Number of uncovered suspects.
    pub uncovered_count: usize,
    /// Number of partial-bleed suspects.
    pub partial_bleed_count: usize,
    /// Number of class-mismatch suspects.
    pub class_mismatch_count: usize,
    /// Number of locale-skip telemetry events.
    pub locale_skipped_count: usize,
}

/// Signed document-context metadata carried inside a session snapshot envelope.
///
/// This extension is the v0.7 bridge for `gaze-document`: it is safe to serialize
/// inside the owner-only snapshot envelope, while agent-facing files keep using
/// non-sensitive mirrors. The single `schema_version` is bundle-level; sub-files
/// do not carry independent schema versions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct DocumentExtension {
    /// Bundle-level schema version shared by clean, layout, preview, report, and manifest files.
    pub schema_version: u16,
    /// SHA-256 of `clean.md` NFC-normalized bytes.
    pub clean_md_sha256: [u8; 32],
    /// SHA-256 of canonical `layout.json` bytes.
    pub layout_json_sha256: [u8; 32],
    /// SHA-256 of canonical `report.json` bytes.
    pub report_json_sha256: [u8; 32],
    /// SHA-256 of `preview-redacted.png` bytes when a preview is present.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preview_png_sha256: Option<[u8; 32]>,
    /// Page count reported for the source document.
    pub page_count: u32,
    /// Audit session id mirrored from the writing session for cross-pane correlation.
    pub audit_session_id: String,
    /// Signed clean.md byte spans for every emitted token.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub clean_spans: Vec<EmittedTokenSpan>,
    /// Codec audit rows for the decode path that produced this document extension.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub codec_audit: Vec<CodecAuditRow>,
}

impl DocumentExtension {
    /// Starts a document extension builder for one bundle schema version.
    pub fn builder(schema_version: u16) -> DocumentExtensionBuilder {
        DocumentExtensionBuilder {
            schema_version,
            clean_md_sha256: None,
            layout_json_sha256: None,
            report_json_sha256: None,
            preview_png_sha256: None,
            page_count: None,
            audit_session_id: None,
            clean_spans: Vec::new(),
            codec_audit: Vec::new(),
        }
    }
}

/// Builder for [`DocumentExtension`] that requires signed integrity-binding fields.
#[derive(Debug, Clone)]
#[must_use]
pub struct DocumentExtensionBuilder {
    schema_version: u16,
    clean_md_sha256: Option<[u8; 32]>,
    layout_json_sha256: Option<[u8; 32]>,
    report_json_sha256: Option<[u8; 32]>,
    preview_png_sha256: Option<[u8; 32]>,
    page_count: Option<u32>,
    audit_session_id: Option<String>,
    clean_spans: Vec<EmittedTokenSpan>,
    codec_audit: Vec<CodecAuditRow>,
}

impl DocumentExtensionBuilder {
    pub fn clean_md_sha256(mut self, hash: [u8; 32]) -> Self {
        self.clean_md_sha256 = Some(hash);
        self
    }

    pub fn layout_json_sha256(mut self, hash: [u8; 32]) -> Self {
        self.layout_json_sha256 = Some(hash);
        self
    }

    pub fn report_json_sha256(mut self, hash: [u8; 32]) -> Self {
        self.report_json_sha256 = Some(hash);
        self
    }

    pub fn preview_png_sha256(mut self, hash: [u8; 32]) -> Self {
        self.preview_png_sha256 = Some(hash);
        self
    }

    pub fn page_count(mut self, page_count: u32) -> Self {
        self.page_count = Some(page_count);
        self
    }

    pub fn audit_session_id(mut self, audit_session_id: impl Into<String>) -> Self {
        self.audit_session_id = Some(audit_session_id.into());
        self
    }

    pub fn clean_spans(mut self, clean_spans: Vec<EmittedTokenSpan>) -> Self {
        self.clean_spans = clean_spans;
        self
    }

    pub fn codec_audit(mut self, codec_audit: Vec<CodecAuditRow>) -> Self {
        self.codec_audit = codec_audit;
        self
    }

    pub fn build(self) -> Result<DocumentExtension, DocumentExtensionError> {
        Ok(DocumentExtension {
            schema_version: self.schema_version,
            clean_md_sha256: self
                .clean_md_sha256
                .ok_or(DocumentExtensionError::MissingField("clean_md_sha256"))?,
            layout_json_sha256: self
                .layout_json_sha256
                .ok_or(DocumentExtensionError::MissingField("layout_json_sha256"))?,
            report_json_sha256: self
                .report_json_sha256
                .ok_or(DocumentExtensionError::MissingField("report_json_sha256"))?,
            preview_png_sha256: self.preview_png_sha256,
            page_count: self
                .page_count
                .ok_or(DocumentExtensionError::MissingField("page_count"))?,
            audit_session_id: self
                .audit_session_id
                .ok_or(DocumentExtensionError::MissingField("audit_session_id"))?,
            clean_spans: self.clean_spans,
            codec_audit: self.codec_audit,
        })
    }
}

/// Errors returned while building a [`DocumentExtension`].
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum DocumentExtensionError {
    #[error("missing document extension field: {0}")]
    MissingField(&'static str),
}

/// Provenance of text extracted from a document or transcript source.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum TextOrigin {
    /// Text came from OCR over pixels.
    Ocr,
    /// Text came from an embedded text layer.
    EmbeddedText,
    /// Text came from an audio/video transcript.
    Transcript,
    /// Text came from multiple extraction paths.
    Hybrid,
}

/// Orthogonal document codec capabilities delivered or advertised by a codec.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CodecCapabilitySet {
    /// Codec can emit text.
    pub text: bool,
    /// Codec can emit layout geometry.
    pub layout: bool,
    /// Codec can emit confidence buckets.
    pub confidence: bool,
    /// Codec can emit timestamps.
    pub timestamps: bool,
}

impl CodecCapabilitySet {
    /// Text-only capability set.
    pub const TEXT_ONLY: Self = Self {
        text: true,
        layout: false,
        confidence: false,
        timestamps: false,
    };

    /// Builds a codec capability bitset.
    pub const fn new(text: bool, layout: bool, confidence: bool, timestamps: bool) -> Self {
        Self {
            text,
            layout,
            confidence,
            timestamps,
        }
    }

    /// Returns true when this set contains every requested capability bit.
    pub fn contains(self, requested: Self) -> bool {
        (!requested.text || self.text)
            && (!requested.layout || self.layout)
            && (!requested.confidence || self.confidence)
            && (!requested.timestamps || self.timestamps)
    }
}

/// Per-codec declaration for text extraction density checks.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ExtractionDensityPolicy {
    /// Require at least this many extracted text bytes per source KiB.
    Required(f32),
    /// Explicit exemption with an audit-visible reason.
    Exempt { reason: String },
}

impl Default for ExtractionDensityPolicy {
    fn default() -> Self {
        Self::Exempt {
            reason: "calibration_pending".to_string(),
        }
    }
}

/// Metadata-only audit row emitted by a document codec.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CodecAuditRow {
    /// Stable codec id, such as `gaze.codec.tesseract`.
    pub codec_id: String,
    /// Adapter crate version, distinct from engine provenance.
    pub codec_version: String,
    /// Accepted MIME type for the decode.
    pub accepted_mime: String,
    /// Capabilities advertised by the codec.
    pub advertised: CodecCapabilitySet,
    /// Capabilities delivered for this decode.
    pub delivered: CodecCapabilitySet,
    /// Text provenance reported by the codec.
    pub text_origin: TextOrigin,
    /// Codec-output schema version, decoupled from bundle schema version.
    pub codec_output_schema_version: u16,
    /// Hash of canonical codec options, never the options themselves.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub options_hash_hex: Option<String>,
    /// Engine provenance string, without paths or raw source text.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub engine_provenance: Option<String>,
    /// Extraction density policy declared by the codec for this MIME.
    pub extraction_density_policy: ExtractionDensityPolicy,
}

impl CodecAuditRow {
    /// Builds a metadata-only codec audit row.
    pub fn new(
        codec_id: impl Into<String>,
        codec_version: impl Into<String>,
        accepted_mime: impl Into<String>,
        text_origin: TextOrigin,
    ) -> Self {
        Self {
            codec_id: codec_id.into(),
            codec_version: codec_version.into(),
            accepted_mime: accepted_mime.into(),
            advertised: CodecCapabilitySet::default(),
            delivered: CodecCapabilitySet::default(),
            text_origin,
            codec_output_schema_version: 1,
            options_hash_hex: None,
            engine_provenance: None,
            extraction_density_policy: ExtractionDensityPolicy::default(),
        }
    }
}

/// A suspected missed PII span reported by a [`SafetyNet`].
///
/// The safety net is not authoritative; a `LeakReport` is a signal, not a confirmed
/// leak. False positives are expected. Review reports and adjust policy or recognizer
/// thresholds.
#[derive(Debug, Clone, Default, PartialEq)]
#[non_exhaustive]
pub struct LeakReport {
    /// Suspected leaks, containing metadata only.
    pub suspects: Vec<LeakSuspect>,
    /// Bytes-free telemetry events.
    pub telemetry: Vec<LeakReportTelemetry>,
    /// Aggregated counts for callers that do not need full suspect metadata.
    pub stats: LeakReportStats,
    /// Optional replay hash.
    ///
    /// Replay determinism is guaranteed only when command path, checkpoint,
    /// operating point, min score, and decode parameters are fixed externally.
    pub replay_hash: Option<String>,
}

impl LeakReport {
    /// Builds a report from suspects and telemetry.
    pub fn from_parts(
        suspects: Vec<LeakSuspect>,
        telemetry: Vec<LeakReportTelemetry>,
    ) -> LeakReport {
        let mut stats = LeakReportStats {
            suspect_count: suspects.len(),
            locale_skipped_count: telemetry
                .iter()
                .filter(|event| matches!(event, LeakReportTelemetry::LocaleSkipped { .. }))
                .count(),
            ..LeakReportStats::default()
        };
        for suspect in &suspects {
            match suspect.kind {
                LeakKind::Uncovered => stats.uncovered_count += 1,
                LeakKind::PartialBleed { .. } => stats.partial_bleed_count += 1,
                LeakKind::ClassMismatch { .. } => stats.class_mismatch_count += 1,
            }
        }
        LeakReport {
            suspects,
            telemetry,
            stats,
            replay_hash: None,
        }
    }

    /// Merges another report into this report.
    pub fn extend(&mut self, other: LeakReport) {
        self.suspects.extend(other.suspects);
        self.telemetry.extend(other.telemetry);
        *self = LeakReport::from_parts(
            std::mem::take(&mut self.suspects),
            std::mem::take(&mut self.telemetry),
        );
    }
}

/// Closed set of upstream OpenAI Privacy Filter labels accepted by Gaze.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum OpenAiPrivateLabel {
    /// `private_person`.
    PrivatePerson,
    /// `private_address`.
    PrivateAddress,
    /// `private_email`.
    PrivateEmail,
    /// `private_phone`.
    PrivatePhone,
    /// `private_url`.
    PrivateUrl,
    /// `private_date`.
    PrivateDate,
    /// `account_number`.
    AccountNumber,
    /// `secret`.
    Secret,
}

impl OpenAiPrivateLabel {
    /// Returns the raw upstream label.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::PrivatePerson => "private_person",
            Self::PrivateAddress => "private_address",
            Self::PrivateEmail => "private_email",
            Self::PrivatePhone => "private_phone",
            Self::PrivateUrl => "private_url",
            Self::PrivateDate => "private_date",
            Self::AccountNumber => "account_number",
            Self::Secret => "secret",
        }
    }
}

/// True when byte offset `at` in `text` sits between two alphanumeric characters, so a span
/// edge there would cut a word.
///
/// This is the one word rule every safety-net stage shares: model decoders assemble spans from
/// whole words with it, and the pipeline refuses to act on a word-like suspect whose edge it
/// flags. Offsets that are out of range or not on a character boundary return false.
pub fn is_inside_word(text: &str, at: usize) -> bool {
    let before = text.get(..at).and_then(|head| head.chars().next_back());
    let after = text.get(at..).and_then(|tail| tail.chars().next());
    before.is_some_and(is_word_char) && after.is_some_and(is_word_char)
}

/// `span` grown outward until neither edge cuts a word under [`is_inside_word`].
///
/// A model reports spans on sub-word pieces; an edge between two pieces leaves the rest of the
/// word raw (`jorunn vas` of `jorunn vasquez`). Out-of-range or off-boundary spans come back
/// unchanged.
pub fn expand_to_word_edges(text: &str, span: Range<usize>) -> Range<usize> {
    if span.start > span.end
        || !text.is_char_boundary(span.start)
        || !text.is_char_boundary(span.end)
    {
        return span;
    }
    let mut start = span.start;
    while is_inside_word(text, start) {
        start -= text[..start].chars().next_back().map_or(0, char::len_utf8);
    }
    let mut end = span.end;
    while is_inside_word(text, end) {
        end += text[end..].chars().next().map_or(0, char::len_utf8);
    }
    start..end
}

/// `span` grown over the name parts glued to it by a hyphen or apostrophe.
///
/// A double surname or a particle is one name: a copy or model span that stops at
/// `Vasquez` in `Vasquez-Ellery` or starts at `Brien` in `O'Brien` leaves the rest raw.
/// Forward, a continuation needs at least two letters, so a possessive `'s` is not taken.
/// Backward, one letter is enough (`O'`, `d'`). A continuation that runs into a digit is not
/// a name part and is not taken. Out-of-range or off-boundary spans come back unchanged.
pub fn extend_over_name_joiners(text: &str, span: Range<usize>) -> Range<usize> {
    const JOINERS: [char; 3] = ['-', '\'', '\u{2019}'];
    if span.start > span.end
        || !text.is_char_boundary(span.start)
        || !text.is_char_boundary(span.end)
    {
        return span;
    }
    let mut end = span.end;
    loop {
        let mut rest = text[end..].chars();
        if !rest.next().is_some_and(|ch| JOINERS.contains(&ch)) {
            break;
        }
        let letters = rest.take_while(|ch| ch.is_alphabetic()).collect::<Vec<_>>();
        let joiner_len = text[end..].chars().next().map_or(0, char::len_utf8);
        let next = end + joiner_len + letters.iter().map(|ch| ch.len_utf8()).sum::<usize>();
        if letters.len() < 2 || is_inside_word(text, next) {
            break;
        }
        end = next;
    }
    let mut start = span.start;
    loop {
        let mut back = text[..start].chars().rev();
        if !back.next().is_some_and(|ch| JOINERS.contains(&ch)) {
            break;
        }
        let letters = back.take_while(|ch| ch.is_alphabetic()).collect::<Vec<_>>();
        let joiner_len = text[..start].chars().next_back().map_or(0, char::len_utf8);
        let prev = start - joiner_len - letters.iter().map(|ch| ch.len_utf8()).sum::<usize>();
        if letters.is_empty() || is_inside_word(text, prev) {
            break;
        }
        start = prev;
    }
    start..end
}

/// The one word-character rule behind [`is_inside_word`] and
/// [`word_run_extends_identifier`]: Unicode alphanumeric. Both edge checks must agree on what a
/// word is, so neither may grow its own predicate.
fn is_word_char(ch: char) -> bool {
    ch.is_alphanumeric()
}

/// True when the word run starting at byte offset `at` in `text` could be more of an identifier:
/// it holds a digit (Unicode numeric), an underscore, or any other word character that is not a
/// letter. A run of letters only (`BIC`, `und`, `Überweisung`) is a label or a word glued to the
/// value, not more value. An empty run, an offset out of range, or one not on a character
/// boundary returns false.
///
/// This is the trailing boundary for identifier recognizers whose pattern must not end in `\b`:
/// `iban.structural` matches a registry-length candidate without a trailing
/// boundary so a compact IBAN glued to the next label (`IBAN AT611904300234573201BIC`) is still a
/// candidate, and this decides whether what follows is a label or the rest of a longer opaque
/// token (`AT611904300234573201XQ7`). Rust `regex` has no lookahead, so it cannot be said in the
/// pattern. The word run reads the same characters as [`is_inside_word`] plus `_`, which joins
/// identifiers and which `\b` counts as a word character; a combining mark is not a word
/// character to either check and ends the run.
pub fn word_run_extends_identifier(text: &str, at: usize) -> bool {
    text.get(at..).is_some_and(|tail| {
        tail.chars()
            .take_while(|ch| is_word_char(*ch) || *ch == '_')
            .any(|ch| !ch.is_alphabetic())
    })
}

/// Closed safety-net PII vocabulary before mapping into `PiiClass`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum SafetyNetPiiClass {
    /// Email address.
    Email,
    /// Person name.
    Name,
    /// Location or address.
    Location,
    /// Phone number.
    Phone,
    /// URL.
    Url,
    /// Date.
    Date,
    /// Account number.
    AccountNumber,
    /// Secret.
    Secret,
    /// Building or house number.
    BuildingNumber,
    /// Vehicle licence plate.
    LicensePlate,
    /// Account username or handle.
    Username,
    /// Postal or ZIP code.
    PostalCode,
    /// Tax identification number.
    TaxId,
}

impl SafetyNetPiiClass {
    /// Maps the safety-net class into the shared pipeline class vocabulary.
    pub fn to_pii_class(self) -> PiiClass {
        match self {
            Self::Email => PiiClass::Email,
            Self::Name => PiiClass::Name,
            Self::Location => PiiClass::Location,
            Self::Phone => PiiClass::custom("phone").expect("valid custom class"),
            Self::Url => PiiClass::custom("url").expect("valid custom class"),
            Self::Date => PiiClass::custom("date").expect("valid custom class"),
            Self::AccountNumber => PiiClass::custom("account_number").expect("valid custom class"),
            Self::Secret => PiiClass::custom("secret").expect("valid custom class"),
            Self::BuildingNumber => {
                PiiClass::custom("building_number").expect("valid custom class")
            }
            Self::LicensePlate => PiiClass::custom("license_plate").expect("valid custom class"),
            Self::Username => PiiClass::custom("username").expect("valid custom class"),
            Self::PostalCode => PiiClass::custom("postal_code").expect("valid custom class"),
            Self::TaxId => PiiClass::custom("tax_id").expect("valid custom class"),
        }
    }
}

/// Exhaustive, closed error set for safety-net execution.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum SafetyNetError {
    /// Safety net was explicitly requested but is unavailable.
    #[error("safety net unavailable: {reason}")]
    Unavailable {
        /// Sanitized reason.
        reason: String,
    },
    /// Required model weights or checkpoint are missing.
    #[error("safety net weights missing: {path}")]
    WeightsMissing {
        /// Sanitized path or identifier.
        path: String,
    },
    /// Backend model could not be loaded or reached.
    #[error("safety net model unavailable: {reason}")]
    ModelUnavailable {
        /// Sanitized reason.
        reason: String,
    },
    /// Backend model artifacts failed integrity verification.
    #[error("safety net model integrity mismatch: expected={expected}, actual={actual}")]
    ModelIntegrityMismatch {
        /// Expected SHA256 digest.
        expected: String,
        /// Actual SHA256 digest.
        actual: String,
    },
    /// Input exceeded configured backend limit.
    #[error("safety net input too large: limit={limit}, actual={actual}")]
    InputTooLarge {
        /// Configured byte limit.
        limit: usize,
        /// Actual byte length.
        actual: usize,
    },
    /// Backend runtime failed.
    #[error("safety net runtime failed: {message}")]
    Runtime {
        /// Sanitized diagnostic message.
        message: String,
    },
    /// Backend returned invalid output.
    #[error("safety net invalid output: {message}")]
    InvalidOutput {
        /// Sanitized diagnostic message.
        message: String,
    },
}

/// Disposition applied to a detected PII span.
///
/// | Variant | Restorable | Output shape |
/// |---------|------------|--------------|
/// | `Tokenize` | Yes | Opaque token: `<hex:Class_N>` |
/// | `FormatPreserve` | Yes | Realistic-looking pseudonym (e.g., `email1.hex@gaze-fake.invalid`) |
/// | `Redact` | No | Literal `[REDACTED]` -- original value is gone |
/// | `Generalize` | No | Class label (e.g., `[Email]`) -- original value is gone |
/// | `Preserve` | - | Passes through unchanged |
///
/// `Action` is `#[non_exhaustive]`. Use a wildcard arm in exhaustive matches.
/// When restore is required, use `Tokenize` or `FormatPreserve` -- `Redact` and
/// `Generalize` are irreversible.
///
/// Serialized with the canonical audit-row spelling (`tokenize`, `redact`,
/// `format_preserve`, `generalize`, `preserve`), the same strings as
/// [`Action::as_str`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum Action {
    /// Replace PII with a reversible token.
    Tokenize,
    /// Replace PII with a non-restorable redaction marker.
    Redact,
    /// Replace PII with a reversible format-preserving token.
    FormatPreserve,
    /// Replace PII with a broader category.
    Generalize,
    /// Preserve the original value.
    Preserve,
}

impl Action {
    /// Returns the canonical audit-row spelling.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Tokenize => "tokenize",
            Self::Redact => "redact",
            Self::FormatPreserve => "format_preserve",
            Self::Generalize => "generalize",
            Self::Preserve => "preserve",
        }
    }

    /// Parses a canonical audit-row spelling.
    pub fn from_canonical_str(value: &str) -> Option<Self> {
        match value {
            "tokenize" => Some(Self::Tokenize),
            "redact" => Some(Self::Redact),
            "format_preserve" => Some(Self::FormatPreserve),
            "generalize" => Some(Self::Generalize),
            "preserve" => Some(Self::Preserve),
            _ => None,
        }
    }

    /// Position in the fail-closed strictness order, higher is stricter:
    ///
    /// | Rank | Action | Original bytes in output | Restorable |
    /// |------|--------|--------------------------|------------|
    /// | 4 | `Redact` | none | no |
    /// | 3 | `Tokenize` | none | yes |
    /// | 2 | `Generalize` | none (class label only) | no |
    /// | 1 | `FormatPreserve` | none (class-shaped fake) | yes |
    /// | 0 | `Preserve` | all | - |
    ///
    /// The order is used when a collision-family token
    /// (`custom:family:<name>`) has no explicit policy rule and takes the
    /// strictest action among its member classes' rules and its own default.
    /// Between two actions that leak no original byte, the non-restorable one
    /// ranks higher: an adopter who redacts one member does not want that value
    /// restored downstream, and redacting the other member only costs
    /// restorability (axis 2), never a leak (axis 1). `Generalize` ranks above
    /// `FormatPreserve` on the same tie-break. An explicit family rule overrides
    /// the derivation.
    pub const fn strictness_rank(self) -> u8 {
        match self {
            Self::Redact => 4,
            Self::Tokenize => 3,
            Self::Generalize => 2,
            Self::FormatPreserve => 1,
            Self::Preserve => 0,
        }
    }

    /// The stricter of two actions under [`Action::strictness_rank`]; `self`
    /// wins a tie.
    pub fn strictest(self, other: Self) -> Self {
        if other.strictness_rank() > self.strictness_rank() {
            other
        } else {
            self
        }
    }

    /// Whether the action replaces the span it applies to: every action but
    /// `Preserve` (the actions ranked above 0 by [`Action::strictness_rank`]).
    ///
    /// Residual coverage admits a losing candidate's evidence only when every
    /// action in its overlap component is protective. The gate used to be "is
    /// exactly `tokenize`", which let a stricter action on a neighbour, or on
    /// the family class a loser resolves through, silently drop coverage of
    /// the loser's remaining bytes.
    pub const fn is_protective(self) -> bool {
        match self {
            Self::Tokenize | Self::Redact | Self::Generalize | Self::FormatPreserve => true,
            Self::Preserve => false,
        }
    }
}

/// Conflict resolution tier that selected or rejected a candidate.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ConflictTier {
    /// No conflict resolution was needed.
    None,
    /// Class priority decided the conflict.
    ClassPriority,
    /// Rule priority decided the conflict.
    RulePriority,
    /// Candidate score decided the conflict.
    Score,
    /// Span length decided the conflict.
    SpanLength,
    /// Same-class containment validator result decided the conflict.
    Validator,
    /// Strict same-class containment selected the span protecting more bytes.
    SameClassContainment,
    /// Pre-resolver validator veto rejected the candidate.
    ValidatorVeto,
    /// Cross-class collision-family policy decided the conflict.
    CollisionPolicy,
    /// Mandatory-anchor context was missing, so family-level fallback was emitted.
    AnchoredContext,
    /// A builtin-class span (`Email`/`Name`/`Organization`/`Location`) strictly
    /// inside a custom-class structured span lost to the enclosing span, so a
    /// structured identifier is never split around a sub-token.
    StructuredContainment,
    /// A candidate that wholly contains a candidate of another class won the
    /// whole span as one token: its evidence tier (validator passed >
    /// anchored or structural cue > plain regex or dictionary > learned NER)
    /// is at least the contained candidate's, ties going to the container.
    /// The contained candidate is recorded as a merged source.
    ContainmentPrecedence,
    /// A residual fragment replaced bytes inside a `preserve` selection
    /// because a class the policy protects also claimed them: protection beat
    /// preservation on exactly those bytes.
    ProtectionOverride,
    /// Recognizer identifier decided the conflict.
    RecognizerId,
    /// Candidate was merged with another candidate.
    Merged,
    /// Safety-net redact mode stripped a suspect span.
    Redact,
    /// Safety-net resolve mode promoted a suspect span into a reversible token.
    Resolve,
    /// Safety-net fallback policy decided the outcome.
    Fallback,
    /// The repeat-value sweep protected a copy of a value the manifest
    /// already holds from rule-based evidence.
    ManifestSweep,
}

impl ConflictTier {
    /// Every variant, for closed-vocabulary checks (component ledger records).
    #[doc(hidden)]
    pub const ALL: &'static [Self] = &[
        Self::None,
        Self::ClassPriority,
        Self::RulePriority,
        Self::Score,
        Self::SpanLength,
        Self::Validator,
        Self::SameClassContainment,
        Self::ValidatorVeto,
        Self::CollisionPolicy,
        Self::AnchoredContext,
        Self::StructuredContainment,
        Self::ContainmentPrecedence,
        Self::ProtectionOverride,
        Self::RecognizerId,
        Self::Merged,
        Self::Redact,
        Self::Resolve,
        Self::Fallback,
        Self::ManifestSweep,
    ];

    /// Fails to compile when a variant is added without extending [`Self::ALL`].
    #[allow(dead_code)]
    const fn all_is_exhaustive(value: Self) {
        match value {
            Self::None
            | Self::ClassPriority
            | Self::RulePriority
            | Self::Score
            | Self::SpanLength
            | Self::Validator
            | Self::SameClassContainment
            | Self::ValidatorVeto
            | Self::CollisionPolicy
            | Self::AnchoredContext
            | Self::StructuredContainment
            | Self::ContainmentPrecedence
            | Self::ProtectionOverride
            | Self::RecognizerId
            | Self::Merged
            | Self::Redact
            | Self::Resolve
            | Self::Fallback
            | Self::ManifestSweep => {}
        }
    }

    /// Returns the canonical audit-row spelling.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::None => "none",
            Self::ClassPriority => "class_priority",
            Self::RulePriority => "rule_priority",
            Self::Score => "score",
            Self::SpanLength => "span_length",
            Self::Validator => "validator",
            Self::SameClassContainment => "same_class_containment",
            Self::ValidatorVeto => "validator_veto",
            Self::CollisionPolicy => "collision_policy",
            Self::AnchoredContext => "anchored_context",
            Self::StructuredContainment => "structured_containment",
            Self::ContainmentPrecedence => "containment_precedence",
            Self::ProtectionOverride => "protection_override",
            Self::RecognizerId => "recognizer_id",
            Self::Merged => "merged",
            Self::Redact => "redact",
            Self::Resolve => "resolve",
            Self::Fallback => "fallback",
            Self::ManifestSweep => "manifest_sweep",
        }
    }

    /// Parses a canonical audit-row spelling.
    pub fn from_canonical_str(value: &str) -> Option<Self> {
        match value {
            "none" => Some(Self::None),
            "class_priority" => Some(Self::ClassPriority),
            "rule_priority" => Some(Self::RulePriority),
            "score" => Some(Self::Score),
            "span_length" => Some(Self::SpanLength),
            "validator" => Some(Self::Validator),
            "same_class_containment" => Some(Self::SameClassContainment),
            "validator_veto" => Some(Self::ValidatorVeto),
            "collision_policy" => Some(Self::CollisionPolicy),
            "anchored_context" => Some(Self::AnchoredContext),
            "structured_containment" => Some(Self::StructuredContainment),
            "containment_precedence" => Some(Self::ContainmentPrecedence),
            "protection_override" => Some(Self::ProtectionOverride),
            "recognizer_id" => Some(Self::RecognizerId),
            "merged" => Some(Self::Merged),
            "redact" => Some(Self::Redact),
            "resolve" => Some(Self::Resolve),
            "fallback" => Some(Self::Fallback),
            "manifest_sweep" => Some(Self::ManifestSweep),
            _ => None,
        }
    }
}

/// Safety-net fallback reason recorded in metadata-only audit rows.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(rename_all = "snake_case")]
pub enum FallbackReason {
    /// The suspect overlapped an existing emitted token in a way that could not be promoted.
    #[serde(alias = "OverlapConflict")]
    OverlapConflict,
    /// A validator rejected the promoted candidate.
    #[serde(alias = "ValidatorVeto")]
    ValidatorVeto,
    /// A mandatory anchor was missing for the promoted candidate.
    #[serde(alias = "AnchorMissing")]
    AnchorMissing,
    /// A follow-up safety-net pass still observed a suspect.
    #[serde(alias = "ResidualSuspect")]
    ResidualSuspect,
}

impl FallbackReason {
    /// Returns the canonical audit-row and JSON spelling.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::OverlapConflict => "overlap_conflict",
            Self::ValidatorVeto => "validator_veto",
            Self::AnchorMissing => "anchor_missing",
            Self::ResidualSuspect => "residual_suspect",
        }
    }

    /// Parses a canonical audit-row spelling.
    pub fn from_canonical_str(value: &str) -> Option<Self> {
        match value {
            "overlap_conflict" => Some(Self::OverlapConflict),
            "validator_veto" => Some(Self::ValidatorVeto),
            "anchor_missing" => Some(Self::AnchorMissing),
            "residual_suspect" => Some(Self::ResidualSuspect),
            _ => None,
        }
    }
}

/// Source document kind for metadata-only audit logging.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum DocumentKind {
    /// Structured key/value document.
    Structured,
    /// Plain text document.
    Text,
}

impl DocumentKind {
    /// Returns the canonical audit-row spelling.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Structured => "structured",
            Self::Text => "text",
        }
    }

    /// Parses a canonical audit-row spelling.
    pub fn from_canonical_str(value: &str) -> Option<Self> {
        match value {
            "structured" => Some(Self::Structured),
            "text" => Some(Self::Text),
            _ => None,
        }
    }
}

/// One row of redaction metadata emitted to a [`RedactionLogger`].
///
/// Fields identify the PII class, action taken, session ID, source document kind,
/// conflict-resolution metadata, and timestamp. Does **not** contain the original PII
/// value, the token string, or any identifiable content beyond what a compliance audit
/// requires.
///
/// `RedactionEntry` is `#[non_exhaustive]`; adopters must construct via the public
/// constructor or destructure with a wildcard pattern.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct RedactionEntry {
    /// Detector or recognizer source identifier.
    pub source: String,
    /// Stable semantic recognizer identifier, when available.
    pub recognizer_id: Option<String>,
    /// Versioned recognizer artifact/rule identifier, when available.
    pub recognizer_version_id: Option<String>,
    /// PII class affected by the decision.
    pub class: PiiClass,
    /// Policy action applied to the span.
    pub action: Action,
    /// Optional structured field name.
    pub field_name: Option<String>,
    /// Source document kind.
    pub document_kind: DocumentKind,
    /// Whether this entry records a loser in conflict resolution.
    pub conflict_loser: bool,
    /// Conflict tier that decided the outcome.
    pub decided_by: ConflictTier,
    /// Creation timestamp in epoch milliseconds.
    pub created_at: i64,
    /// Optional session identifier.
    pub session_id: Option<String>,
    /// Optional validator or regex-guard refusal reason for a vetoed candidate.
    pub validator_fail_reason: Option<ValidatorFailReason>,
    /// Closed reason for a labelled value boundary or length limit.
    pub labelled_value_scan_reason: Option<LabelledValueScanReason>,
    /// Optional ambiguity metadata for a family-level fallback.
    pub ambiguity_record: Option<AmbiguityRecord>,
    /// Collision family that influenced this decision.
    pub collision_family: Option<String>,
    /// Collision variant that influenced this decision.
    pub collision_variant: Option<String>,
    /// Safety-net fallback reason, when fallback policy handled the row.
    pub fallback_triggered: Option<FallbackReason>,
    /// NER/pipeline provenance stage for audit-only producer attribution.
    pub provenance_stage: Option<String>,
    pub provenance_model_id: Option<String>,
    pub provenance_model_version: Option<String>,
    pub provenance_artifact_sha256: Option<String>,
    pub provenance_tokenizer_sha256: Option<String>,
    pub provenance_locale_resolved: Option<String>,
    pub provenance_locale_match_kind: Option<String>,
    pub provenance_canonical_class: Option<String>,
    pub provenance_native_class: Option<String>,
    pub provenance_confidence: Option<String>,
    pub provenance_merged_from: Option<String>,
    /// Locale-aware safety-net backend ids dropped by first-match-wins routing.
    pub backend_silently_dropped: Option<Vec<String>>,
    pub restore_policy: Option<String>,
    pub restore_decision: Option<String>,
    pub restore_unknown_token_count: Option<u64>,
    pub restore_manifest_bypass_count: Option<u64>,
    pub restore_fresh_pii_count: Option<u64>,
    pub restore_phase_mask: Option<u32>,
    pub restore_trap_shape_count: Option<u64>,
}

impl Serialize for RedactionEntry {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct;

        let mut len = 14;
        if self.recognizer_id.is_some() {
            len += 1;
        }
        if self.recognizer_version_id.is_some() {
            len += 1;
        }
        len += [
            self.provenance_stage.as_ref(),
            self.provenance_model_id.as_ref(),
            self.provenance_model_version.as_ref(),
            self.provenance_artifact_sha256.as_ref(),
            self.provenance_tokenizer_sha256.as_ref(),
            self.provenance_locale_resolved.as_ref(),
            self.provenance_locale_match_kind.as_ref(),
            self.provenance_canonical_class.as_ref(),
            self.provenance_native_class.as_ref(),
            self.provenance_confidence.as_ref(),
            self.provenance_merged_from.as_ref(),
        ]
        .into_iter()
        .filter(|value| value.is_some())
        .count();
        if self.backend_silently_dropped.is_some() {
            len += 1;
        }
        len += [self.restore_policy.as_ref(), self.restore_decision.as_ref()]
            .into_iter()
            .filter(|value| value.is_some())
            .count();
        len += [
            self.restore_unknown_token_count.is_some(),
            self.restore_manifest_bypass_count.is_some(),
            self.restore_fresh_pii_count.is_some(),
            self.restore_phase_mask.is_some(),
            self.restore_trap_shape_count.is_some(),
        ]
        .into_iter()
        .filter(|value| *value)
        .count();
        let mut state = serializer.serialize_struct("RedactionEntry", len)?;
        state.serialize_field("source", &self.source)?;
        if let Some(recognizer_id) = &self.recognizer_id {
            state.serialize_field("recognizer_id", recognizer_id)?;
        }
        if let Some(recognizer_version_id) = &self.recognizer_version_id {
            state.serialize_field("recognizer_version_id", recognizer_version_id)?;
        }
        state.serialize_field("class", &self.class.to_canonical_str())?;
        state.serialize_field("action", self.action.as_str())?;
        state.serialize_field("field_name", &self.field_name)?;
        state.serialize_field("document_kind", self.document_kind.as_str())?;
        state.serialize_field("conflict_loser", &self.conflict_loser)?;
        state.serialize_field("decided_by", self.decided_by.as_str())?;
        state.serialize_field("created_at", &self.created_at)?;
        state.serialize_field("session_id", &self.session_id)?;
        state.serialize_field("validator_fail_reason", &self.validator_fail_reason)?;
        state.serialize_field("ambiguity_record", &self.ambiguity_record)?;
        state.serialize_field("collision_family", &self.collision_family)?;
        state.serialize_field("collision_variant", &self.collision_variant)?;
        state.serialize_field("fallback_triggered", &self.fallback_triggered)?;
        if let Some(value) = &self.provenance_stage {
            state.serialize_field("provenance_stage", value)?;
        }
        if let Some(value) = &self.provenance_model_id {
            state.serialize_field("provenance_model_id", value)?;
        }
        if let Some(value) = &self.provenance_model_version {
            state.serialize_field("provenance_model_version", value)?;
        }
        if let Some(value) = &self.provenance_artifact_sha256 {
            state.serialize_field("provenance_artifact_sha256", value)?;
        }
        if let Some(value) = &self.provenance_tokenizer_sha256 {
            state.serialize_field("provenance_tokenizer_sha256", value)?;
        }
        if let Some(value) = &self.provenance_locale_resolved {
            state.serialize_field("provenance_locale_resolved", value)?;
        }
        if let Some(value) = &self.provenance_locale_match_kind {
            state.serialize_field("provenance_locale_match_kind", value)?;
        }
        if let Some(value) = &self.provenance_canonical_class {
            state.serialize_field("provenance_canonical_class", value)?;
        }
        if let Some(value) = &self.provenance_native_class {
            state.serialize_field("provenance_native_class", value)?;
        }
        if let Some(value) = &self.provenance_confidence {
            state.serialize_field("provenance_confidence", value)?;
        }
        if let Some(value) = &self.provenance_merged_from {
            state.serialize_field("provenance_merged_from", value)?;
        }
        if let Some(dropped) = &self.backend_silently_dropped {
            state.serialize_field("backend_silently_dropped", dropped)?;
        }
        if let Some(value) = &self.restore_policy {
            state.serialize_field("restore_policy", value)?;
        }
        if let Some(value) = &self.restore_decision {
            state.serialize_field("restore_decision", value)?;
        }
        if let Some(value) = self.restore_unknown_token_count {
            state.serialize_field("restore_unknown_token_count", &value)?;
        }
        if let Some(value) = self.restore_manifest_bypass_count {
            state.serialize_field("restore_manifest_bypass_count", &value)?;
        }
        if let Some(value) = self.restore_fresh_pii_count {
            state.serialize_field("restore_fresh_pii_count", &value)?;
        }
        if let Some(value) = self.restore_trap_shape_count {
            state.serialize_field("restore_trap_shape_count", &value)?;
        }
        if let Some(value) = self.restore_phase_mask {
            state.serialize_field("restore_phase_mask", &value)?;
        }
        state.end()
    }
}

impl RedactionEntry {
    /// Builds a metadata-only redaction log entry.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        source: impl Into<String>,
        class: PiiClass,
        action: Action,
        field_name: Option<String>,
        document_kind: DocumentKind,
        conflict_loser: bool,
        decided_by: ConflictTier,
        created_at: i64,
        session_id: Option<String>,
    ) -> Self {
        Self {
            source: source.into(),
            class,
            action,
            field_name,
            document_kind,
            conflict_loser,
            decided_by,
            created_at,
            session_id,
            recognizer_id: None,
            recognizer_version_id: None,
            validator_fail_reason: None,
            labelled_value_scan_reason: None,
            ambiguity_record: None,
            collision_family: None,
            collision_variant: None,
            fallback_triggered: None,
            provenance_stage: None,
            provenance_model_id: None,
            provenance_model_version: None,
            provenance_artifact_sha256: None,
            provenance_tokenizer_sha256: None,
            provenance_locale_resolved: None,
            provenance_locale_match_kind: None,
            provenance_canonical_class: None,
            provenance_native_class: None,
            provenance_confidence: None,
            provenance_merged_from: None,
            backend_silently_dropped: None,
            restore_policy: None,
            restore_decision: None,
            restore_unknown_token_count: None,
            restore_manifest_bypass_count: None,
            restore_fresh_pii_count: None,
            restore_phase_mask: None,
            restore_trap_shape_count: None,
        }
    }

    /// Attaches a validator failure reason to this metadata row.
    pub fn with_validator_fail_reason(mut self, reason: ValidatorFailReason) -> Self {
        self.validator_fail_reason = Some(reason);
        self
    }

    /// Attaches an ambiguity record to this metadata row.
    pub fn with_ambiguity_record(mut self, record: AmbiguityRecord) -> Self {
        self.ambiguity_record = Some(record);
        self
    }

    /// Attaches collision-family metadata to this row.
    pub fn with_collision_metadata(
        mut self,
        family: Option<String>,
        variant: Option<String>,
    ) -> Self {
        self.collision_family = family;
        self.collision_variant = variant;
        self
    }

    /// Attaches safety-net fallback metadata to this row.
    pub fn with_fallback_triggered(mut self, reason: FallbackReason) -> Self {
        self.fallback_triggered = Some(reason);
        self
    }

    /// Attaches locale-aware backend ids dropped by first-match-wins routing.
    pub fn with_backend_silently_dropped(mut self, dropped: Vec<String>) -> Self {
        self.backend_silently_dropped = Some(dropped);
        self
    }

    pub fn with_restore_telemetry(mut self, telemetry: RestoreTelemetry) -> Self {
        self.restore_policy = Some(telemetry.restore_policy_str().to_string());
        self.restore_decision = Some(telemetry.restore_decision_str().to_string());
        self.restore_unknown_token_count = Some(telemetry.unknown_token_count);
        self.restore_manifest_bypass_count = Some(telemetry.manifest_bypass_count);
        self.restore_fresh_pii_count = Some(telemetry.fresh_pii_detected_count);
        self.restore_phase_mask = Some(telemetry.phase_execution_mask);
        self.restore_trap_shape_count = Some(telemetry.trap_shape_count);
        self
    }

    /// Attaches recognizer lineage metadata to this row.
    pub fn with_recognizer_metadata(
        mut self,
        recognizer_id: Option<String>,
        recognizer_version_id: Option<String>,
    ) -> Self {
        self.recognizer_id = recognizer_id;
        self.recognizer_version_id = recognizer_version_id;
        self
    }

    #[allow(clippy::too_many_arguments)]
    pub fn with_provenance_metadata(
        mut self,
        stage: Option<String>,
        model_id: Option<String>,
        model_version: Option<String>,
        artifact_sha256: Option<String>,
        tokenizer_sha256: Option<String>,
        locale_resolved: Option<String>,
        locale_match_kind: Option<String>,
        canonical_class: Option<String>,
        native_class: Option<String>,
        confidence: Option<f64>,
        merged_from: Option<String>,
    ) -> Self {
        self.provenance_stage = stage;
        self.provenance_model_id = model_id;
        self.provenance_model_version = model_version;
        self.provenance_artifact_sha256 = artifact_sha256;
        self.provenance_tokenizer_sha256 = tokenizer_sha256;
        self.provenance_locale_resolved = locale_resolved;
        self.provenance_locale_match_kind = locale_match_kind;
        self.provenance_canonical_class = canonical_class;
        self.provenance_native_class = native_class;
        self.provenance_confidence = confidence.map(|value| value.to_string());
        self.provenance_merged_from = merged_from;
        self
    }
}

/// Closed error set for redaction log sinks.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum RedactionLogError {
    /// SQLite-backed redaction log sink failed.
    #[error("sqlite redaction log error: {0}")]
    Sqlite(String),
    /// Non-SQLite redaction log sink failed.
    #[error("backend redaction log error: {0}")]
    Backend(String),
}

/// Trait for audit sinks that receive redaction metadata.
///
/// Implement this for custom audit backends (remote telemetry, structured JSON logs).
/// For SQLite-backed persistence, use `gaze_audit::SqliteLogger`.
///
/// # Contract
///
/// The logger receives **metadata only**: class, action, session ID, timestamp, and
/// other bytes-free audit labels. It never receives the original PII value or the token
/// value. A custom impl that augments entries with raw document text violates the audit
/// isolation contract and will be flagged by the `gaze_module_isolation` Dylint lint
/// when it lives in the wrong crate.
///
/// # Example
///
/// ```rust
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use gaze_types::{RedactionEntry, RedactionLogError, RedactionLogger};
///
/// #[derive(Default)]
/// struct CountLogger(AtomicUsize);
///
/// impl RedactionLogger for CountLogger {
///     fn log(&self, _entry: &RedactionEntry) -> Result<(), RedactionLogError> {
///         self.0.fetch_add(1, Ordering::Relaxed);
///         Ok(())
///     }
/// }
/// ```
pub trait RedactionLogger: Send + Sync {
    /// Records a metadata-only redaction entry.
    fn log(&self, entry: &RedactionEntry) -> Result<(), RedactionLogError>;
}

/// Rulepack recognizer activation tier.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum SafetyTier {
    /// Activates whenever the recognizer's locale projection intersects the active locale chain.
    #[default]
    SafeDefault,
    /// Activates only when an explicit locale or compatibility alias enables locale-shaped rules.
    LocaleGated,
    /// Activates only through adopter opt-in surfaces such as policy-defined custom recognizers.
    OptIn,
}

/// Safety-tier parsing error.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct SafetyTierParseError {
    value: String,
}

impl SafetyTier {
    /// Parses the TOML `safety_tier` string.
    pub fn parse(value: &str) -> Result<Self, SafetyTierParseError> {
        match value {
            "safe_default" => Ok(Self::SafeDefault),
            "locale_gated" => Ok(Self::LocaleGated),
            "opt_in" => Ok(Self::OptIn),
            other => Err(SafetyTierParseError {
                value: other.to_string(),
            }),
        }
    }

    /// Returns the TOML string for this tier.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::SafeDefault => "safe_default",
            Self::LocaleGated => "locale_gated",
            Self::OptIn => "opt_in",
        }
    }
}

impl SafetyTierParseError {
    /// Returns the rejected safety-tier string.
    pub fn value(&self) -> &str {
        &self.value
    }
}

impl fmt::Display for SafetyTierParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "unsupported safety_tier '{}'", self.value)
    }
}

impl std::error::Error for SafetyTierParseError {}

/// Interpretation of a rulepack recognizer's locale metadata.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum LocaleBasis {
    /// `locales` is an eligibility gate matched against the document locale chain.
    #[default]
    Document,
    /// `locales` records identifier-format provenance and never gates eligibility.
    Format,
}

/// Locale-basis parsing error.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct LocaleBasisParseError {
    value: String,
}

impl LocaleBasis {
    /// Parses the TOML `locale_basis` string.
    pub fn parse(value: &str) -> Result<Self, LocaleBasisParseError> {
        match value {
            "document" => Ok(Self::Document),
            "format" => Ok(Self::Format),
            other => Err(LocaleBasisParseError {
                value: other.to_string(),
            }),
        }
    }

    /// Returns the TOML string for this basis.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Document => "document",
            Self::Format => "format",
        }
    }
}

impl LocaleBasisParseError {
    /// Returns the rejected locale-basis string.
    pub fn value(&self) -> &str {
        &self.value
    }
}

impl fmt::Display for LocaleBasisParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "unsupported locale_basis '{}'", self.value)
    }
}

impl std::error::Error for LocaleBasisParseError {}

/// Locale tag recognized by policy and recognizers.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum LocaleTag {
    /// Locale-independent recognizer or policy.
    Global,
    /// German as used in Germany.
    DeDe,
    /// German as used in Austria.
    DeAt,
    /// German as used in Switzerland.
    DeCh,
    /// English as used in the United States.
    EnUs,
    /// English as used in Great Britain.
    EnGb,
    /// English as used in Ireland.
    EnIe,
    /// English as used in Australia.
    EnAu,
    /// English as used in Canada.
    EnCa,
    /// Any other canonical BCP-47-like tag.
    Other(String),
}

/// Locale parsing error.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum LocaleError {
    /// Locale tag is unsupported or invalid.
    Unsupported,
}

impl fmt::Display for LocaleError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            LocaleError::Unsupported => f.write_str("unsupported locale"),
        }
    }
}

impl std::error::Error for LocaleError {}

/// Ordered locale fallback chain.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LocaleChain(Vec<LocaleTag>);

impl LocaleTag {
    /// Global locale constant.
    pub const GLOBAL: LocaleTag = LocaleTag::Global;

    /// Parses a locale tag from policy or CLI input.
    pub fn parse(s: &str) -> Result<LocaleTag, LocaleError> {
        let raw = s.trim().replace('_', "-");
        let normalized = raw.to_ascii_lowercase();
        match normalized.as_str() {
            "global" | "*" => Ok(LocaleTag::Global),
            "de-de" => Ok(LocaleTag::DeDe),
            "de-at" => Ok(LocaleTag::DeAt),
            "de-ch" => Ok(LocaleTag::DeCh),
            "en-us" => Ok(LocaleTag::EnUs),
            "en-gb" => Ok(LocaleTag::EnGb),
            "en-ie" => Ok(LocaleTag::EnIe),
            "en-au" => Ok(LocaleTag::EnAu),
            "en-ca" => Ok(LocaleTag::EnCa),
            "" => Err(LocaleError::Unsupported),
            _ if is_bcp47_parseable(&raw) => Ok(LocaleTag::Other(canonical_other(&raw))),
            _ => Err(LocaleError::Unsupported),
        }
    }

    /// Returns the canonical string form of the locale tag.
    pub fn as_str(&self) -> &str {
        match self {
            LocaleTag::Global => "global",
            LocaleTag::DeDe => "de-DE",
            LocaleTag::DeAt => "de-AT",
            LocaleTag::DeCh => "de-CH",
            LocaleTag::EnUs => "en-US",
            LocaleTag::EnGb => "en-GB",
            LocaleTag::EnIe => "en-IE",
            LocaleTag::EnAu => "en-AU",
            LocaleTag::EnCa => "en-CA",
            LocaleTag::Other(tag) => tag.as_str(),
        }
    }
}

impl LocaleChain {
    /// Builds a locale chain and appends global fallback when absent.
    pub fn from_tags(mut tags: Vec<LocaleTag>) -> LocaleChain {
        ensure_global(&mut tags);
        LocaleChain(tags)
    }

    /// Parses a comma-separated CLI locale chain.
    pub fn from_cli(raw: &str) -> Result<LocaleChain, LocaleError> {
        let tags = raw
            .split(',')
            .map(LocaleTag::parse)
            .collect::<Result<Vec<_>, _>>()?;
        Ok(LocaleChain::from_tags(tags))
    }

    /// Merges policy and CLI locale preferences.
    pub fn merge_policy_and_cli(
        policy: Option<&[LocaleTag]>,
        cli: Option<&[LocaleTag]>,
    ) -> LocaleChain {
        Self::merge_cli_policy_rulepack_default(cli, policy, None)
    }

    /// Merges CLI, policy, rulepack, and default locale preferences.
    pub fn merge_cli_policy_rulepack_default(
        cli: Option<&[LocaleTag]>,
        policy: Option<&[LocaleTag]>,
        rulepack_defaults: Option<&[LocaleTag]>,
    ) -> LocaleChain {
        let tags = cli
            .filter(|tags| !tags.is_empty())
            .or_else(|| policy.filter(|tags| !tags.is_empty()))
            .or_else(|| rulepack_defaults.filter(|tags| !tags.is_empty()))
            .map(|tags| tags.to_vec())
            .unwrap_or_else(|| vec![LocaleTag::Global]);
        LocaleChain::from_tags(tags)
    }

    /// Returns true when a recognizer can run under this locale chain.
    pub fn intersects(&self, recognizer_locales: &[LocaleTag]) -> bool {
        if recognizer_locales.is_empty() {
            return true;
        }
        recognizer_locales.iter().any(|recognizer_locale| {
            *recognizer_locale == LocaleTag::Global
                || self.0.iter().any(|active| active == recognizer_locale)
        })
    }

    /// Returns the locale tags in chain order.
    pub fn as_slice(&self) -> &[LocaleTag] {
        &self.0
    }

    /// Returns the locale chain as canonical strings.
    pub fn to_strings(&self) -> Vec<String> {
        self.0.iter().map(ToString::to_string).collect()
    }
}

impl From<&[LocaleTag]> for LocaleChain {
    fn from(tags: &[LocaleTag]) -> Self {
        let mut owned = tags.to_vec();
        ensure_global(&mut owned);
        LocaleChain(owned)
    }
}

impl fmt::Display for LocaleTag {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// The input document submitted for pseudonymization.
///
/// `RawDocument::Text(String)` for plain or semi-structured text (most LLM workflows).
/// `RawDocument::Structured(BTreeMap<String, Value>)` for JSON-shaped data where
/// column-aware rules apply -- `ColumnRule`s only take effect on structured input.
///
/// `Detection::span` and recognizer candidate spans use **byte** ranges, not char indices.
///
/// `RawDocument` is `#[non_exhaustive]`. Match with a wildcard arm.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum RawDocument {
    /// Structured document values.
    Structured(BTreeMap<String, Value>),
    /// Plain text document.
    Text(String),
}

/// The pseudonymized output from `Pipeline::redact`.
///
/// Mirrors the shape of `RawDocument`: `CleanDocument::Text(String)` or
/// `CleanDocument::Structured(BTreeMap<String, Value>)`. Destructure with a `let`-else
/// or `match`; **there is no `.text()` accessor**.
///
/// ```rust
/// use gaze_types::CleanDocument;
///
/// fn unwrap_text(doc: CleanDocument) -> Option<String> {
///     if let CleanDocument::Text(t) = doc { Some(t) } else { None }
/// }
/// ```
///
/// Contains only tokens or redacted placeholders -- no original PII values.
/// Send this (or its inner string) to the LLM; never send the original `RawDocument`.
///
/// `CleanDocument` is `#[non_exhaustive]`.
#[derive(Debug, Clone, Serialize)]
#[serde(untagged)]
#[non_exhaustive]
pub enum CleanDocument {
    /// Structured document values.
    Structured(BTreeMap<String, Value>),
    /// Plain text document.
    Text(String),
}

/// Minimal structured value representation that avoids a serde_json dependency.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(untagged)]
#[non_exhaustive]
pub enum Value {
    /// Null value.
    Null,
    /// Boolean value.
    Bool(bool),
    /// String value.
    String(String),
    /// Signed 64-bit integer value.
    I64(i64),
    /// Array value.
    Array(Vec<Value>),
    /// Object value.
    Object(BTreeMap<String, Value>),
}

impl Value {
    /// Returns the inner string for string values.
    pub fn as_str(&self) -> Option<&str> {
        match self {
            Self::String(value) => Some(value.as_str()),
            Self::Null | Self::Bool(_) | Self::I64(_) | Self::Array(_) | Self::Object(_) => None,
        }
    }

    /// Returns a scalar string representation used for structured safety-net checks.
    pub fn scalar_to_safety_net_string(&self) -> Option<String> {
        match self {
            Self::String(value) if !value.is_empty() => Some(value.clone()),
            Self::String(_) | Self::Null | Self::Array(_) | Self::Object(_) => None,
            Self::Bool(value) => Some(value.to_string()),
            Self::I64(value) => Some(value.to_string()),
        }
    }
}

impl PartialEq<&str> for Value {
    fn eq(&self, other: &&str) -> bool {
        self.as_str() == Some(*other)
    }
}

/// Value-only dictionary bundle shared with recognizers.
#[derive(Debug, Clone, Default)]
pub struct DictionaryBundle {
    entries: HashMap<String, DictionaryEntry>,
}

/// Request-local dictionary entry; compiled automatons live outside `gaze-types`.
#[derive(Debug, Clone)]
pub struct DictionaryEntry {
    terms: Vec<String>,
    case_sensitive: bool,
    source: DictionarySource,
    record_allowed_kinds: Option<BTreeSet<RecordMatchKind>>,
}

/// Source of a dictionary entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum DictionarySource {
    /// Dictionary supplied by request context.
    Cli,
    /// Dictionary supplied by a rulepack.
    Rulepack,
}

/// Dictionary metadata used for diagnostics and tests.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct DictionaryStats {
    /// Dictionary name.
    pub name: String,
    /// Number of configured terms.
    pub term_count: usize,
    /// Dictionary source.
    pub source: DictionarySource,
}

impl DictionaryStats {
    /// Builds dictionary diagnostics metadata.
    pub fn new(name: impl Into<String>, term_count: usize, source: DictionarySource) -> Self {
        Self {
            name: name.into(),
            term_count,
            source,
        }
    }
}

/// Dictionary declared by a rulepack.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct RulepackDict {
    /// Dictionary name.
    pub name: String,
    /// Dictionary terms.
    pub terms: Vec<String>,
    /// Whether matching is case-sensitive.
    pub case_sensitive: bool,
}

impl RulepackDict {
    /// Builds a rulepack dictionary declaration.
    pub fn new(name: impl Into<String>, terms: Vec<String>, case_sensitive: bool) -> Self {
        Self {
            name: name.into(),
            terms,
            case_sensitive,
        }
    }
}

/// Error raised when constructing invalid dictionary entries.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum DictionaryLoadError {
    /// Dictionary has no terms.
    Empty { name: String },
    /// ASCII-only case-insensitive matching cannot safely cover this entry.
    UnicodeInsensitiveUnsupported { name: String },
}

impl fmt::Display for DictionaryLoadError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty { name } => write!(f, "dictionary '{name}' has no terms"),
            Self::UnicodeInsensitiveUnsupported { name } => write!(
                f,
                "dictionary '{name}' uses unicode terms with case-insensitive matching, unsupported in v0.4.0; use case_sensitive = true"
            ),
        }
    }
}

impl std::error::Error for DictionaryLoadError {}

impl DictionaryBundle {
    /// Builds a bundle from rulepack dictionaries.
    pub fn from_rulepack_terms(terms: &[RulepackDict]) -> Self {
        let mut entries = HashMap::with_capacity(terms.len());
        for dictionary in terms {
            let entry = DictionaryEntry::new(
                &dictionary.name,
                dictionary.terms.clone(),
                dictionary.case_sensitive,
                DictionarySource::Rulepack,
            )
            .expect("Policy validates dictionary terms before bundle construction");
            entries.insert(dictionary.name.clone(), entry);
        }
        Self { entries }
    }

    /// Builds a bundle from pre-built dictionary entries.
    pub fn from_entries(entries: impl IntoIterator<Item = (String, DictionaryEntry)>) -> Self {
        Self {
            entries: entries.into_iter().collect(),
        }
    }

    /// Merges two bundles, preferring entries from the second bundle on name conflicts.
    pub fn merge(a: Self, b: Self) -> Self {
        let mut entries = a.entries;
        entries.extend(b.entries);
        Self { entries }
    }

    /// Returns a dictionary by name.
    pub fn get(&self, name: &str) -> Option<&DictionaryEntry> {
        self.entries.get(name)
    }

    /// Borrows all entries for record-name corroboration within one request.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &DictionaryEntry)> {
        self.entries
            .iter()
            .map(|(name, entry)| (name.as_str(), entry))
    }

    /// Returns sorted dictionary stats.
    pub fn stats(&self) -> Vec<DictionaryStats> {
        let mut stats = self
            .entries
            .iter()
            .map(|(name, entry)| DictionaryStats {
                name: name.clone(),
                term_count: entry.terms.len(),
                source: entry.source,
            })
            .collect::<Vec<_>>();
        stats.sort_by(|a, b| a.name.cmp(&b.name));
        stats
    }
}

impl DictionaryEntry {
    /// Creates a validated value-only dictionary entry.
    pub fn new(
        name: &str,
        terms: Vec<String>,
        case_sensitive: bool,
        source: DictionarySource,
    ) -> Result<Self, DictionaryLoadError> {
        if terms.is_empty() {
            return Err(DictionaryLoadError::Empty {
                name: name.to_string(),
            });
        }
        if !case_sensitive && terms.iter().any(|term| !term.is_ascii()) {
            return Err(DictionaryLoadError::UnicodeInsensitiveUnsupported {
                name: name.to_string(),
            });
        }
        Ok(Self {
            terms,
            case_sensitive,
            source,
            record_allowed_kinds: None,
        })
    }

    /// Carries the caller's record match policy with the request-local terms.
    pub fn with_record_allowed_kinds(mut self, kinds: BTreeSet<RecordMatchKind>) -> Self {
        self.record_allowed_kinds = Some(kinds);
        self
    }

    /// `None` means this is an ordinary dictionary with no record policy.
    pub fn record_allowed_kinds(&self) -> Option<&BTreeSet<RecordMatchKind>> {
        self.record_allowed_kinds.as_ref()
    }

    /// Returns whether matching is case-sensitive.
    pub fn case_sensitive(&self) -> bool {
        self.case_sensitive
    }

    /// Returns configured dictionary terms.
    pub fn terms(&self) -> &[String] {
        &self.terms
    }
}

#[cfg(test)]
mod action_tests {
    use super::*;

    /// `is_protective` and `strictness_rank` are two views of one order: an
    /// action protects the span exactly when it ranks above `preserve`.
    #[test]
    fn protective_means_ranked_above_preserve() {
        for action in [
            Action::Tokenize,
            Action::Redact,
            Action::FormatPreserve,
            Action::Generalize,
            Action::Preserve,
        ] {
            assert_eq!(
                action.is_protective(),
                action.strictness_rank() > Action::Preserve.strictness_rank(),
                "{action:?}"
            );
        }
        assert!(!Action::Preserve.is_protective());
    }
}

#[cfg(test)]
mod word_boundary_tests {
    use super::*;

    const IBAN: &str = "AT611904300234573201";

    fn extends(trailer: &str) -> bool {
        let text = format!("IBAN {IBAN}{trailer}");
        word_run_extends_identifier(&text, 5 + IBAN.len())
    }

    /// Letters glued to the value are a label or a word: ASCII either case, and any Unicode
    /// letter, so `…3201Überweisung` and `…3201und` behave alike.
    #[test]
    fn a_run_of_letters_does_not_extend_the_identifier() {
        for trailer in [
            "",
            "BIC",
            "bic",
            "BIC:BKAUATWW",
            "Überweisung",
            "über",
            "Straße",
            "élan",
        ] {
            assert!(!extends(trailer), "{trailer:?}");
        }
    }

    /// A digit, an underscore, or a non-ASCII digit anywhere in the run could be more identifier.
    #[test]
    fn a_digit_or_underscore_anywhere_in_the_run_extends_the_identifier() {
        for trailer in [
            "1",
            "XQ7",
            "BIC1",
            "_",
            "_x",
            "x_",
            "\u{661}",
            "BIC\u{661}",
            "٣",
        ] {
            assert!(extends(trailer), "{trailer:?}");
        }
    }

    /// The run stops at the first non-word character, so what comes after a separator is not
    /// read, and a combining mark is not a word character to this check or to `is_inside_word`.
    #[test]
    fn the_run_stops_at_a_separator_or_a_combining_mark() {
        for trailer in [" 1234", ":1234", "BIC:1", "\u{301}1", "\u{301}", "-1", ".1"] {
            assert!(!extends(trailer), "{trailer:?}");
        }
        assert!(!is_inside_word("a\u{301}", 1));
    }

    /// Malformed offsets are not an identifier continuation.
    #[test]
    fn out_of_range_or_mid_character_offsets_return_false() {
        assert!(!word_run_extends_identifier("AT61", 99));
        assert!(!word_run_extends_identifier("AT61", 4));
        assert!(!word_run_extends_identifier("ü1", 1));
    }

    /// The two edge checks share one word predicate.
    #[test]
    fn both_edge_checks_agree_on_word_characters() {
        for ch in ['a', 'Z', '9', 'ü', '\u{661}', '_', '-', ' ', '\u{301}', '<'] {
            let text = format!("x{ch}");
            assert_eq!(
                is_inside_word(&text, 1),
                is_word_char(ch),
                "{ch:?}: is_inside_word must follow is_word_char"
            );
            let run_reads_it = word_run_extends_identifier(&format!("{ch}1"), 0);
            assert_eq!(
                run_reads_it,
                is_word_char(ch) || ch == '_',
                "{ch:?}: the run must read exactly the word characters plus underscore"
            );
        }
    }
}

#[cfg(test)]
mod dictionary_tests {
    use super::*;

    #[test]
    fn dictionary_entry_rejects_empty_terms() {
        let err = DictionaryEntry::new("empty", Vec::new(), true, DictionarySource::Cli)
            .expect_err("empty dictionaries must fail closed");

        assert!(matches!(err, DictionaryLoadError::Empty { name } if name == "empty"));
    }

    #[test]
    fn dictionary_entry_rejects_non_ascii_case_insensitive_terms() {
        let err = DictionaryEntry::new(
            "songs",
            vec!["Beyonce".to_string(), "Caf\u{00e9}".to_string()],
            false,
            DictionarySource::Cli,
        )
        .expect_err("unicode case-insensitive dictionaries must fail closed");

        assert!(matches!(
            err,
            DictionaryLoadError::UnicodeInsensitiveUnsupported { name } if name == "songs"
        ));
    }
}

#[cfg(test)]
mod redaction_logger_tests {
    use super::*;

    struct CapturingLogger;

    impl RedactionLogger for CapturingLogger {
        fn log(&self, _entry: &RedactionEntry) -> Result<(), RedactionLogError> {
            Ok(())
        }
    }

    fn assert_send_sync<T: Send + Sync + ?Sized>() {}

    #[test]
    fn fallback_reason_serializes_snake_case_and_accepts_legacy_pascal_case() {
        for (legacy, canonical, value) in [
            (
                "OverlapConflict",
                "overlap_conflict",
                FallbackReason::OverlapConflict,
            ),
            (
                "ValidatorVeto",
                "validator_veto",
                FallbackReason::ValidatorVeto,
            ),
            (
                "AnchorMissing",
                "anchor_missing",
                FallbackReason::AnchorMissing,
            ),
            (
                "ResidualSuspect",
                "residual_suspect",
                FallbackReason::ResidualSuspect,
            ),
        ] {
            let legacy_json = format!(r#""{legacy}""#);
            assert_eq!(
                serde_json::from_str::<FallbackReason>(&legacy_json)
                    .expect("legacy fallback reason"),
                value
            );
            assert_eq!(
                serde_json::to_string(&value).expect("fallback reason"),
                format!(r#""{canonical}""#)
            );
        }
    }

    #[test]
    fn audit_enum_canonical_forms_round_trip() {
        for value in [
            Action::Tokenize,
            Action::Redact,
            Action::FormatPreserve,
            Action::Generalize,
            Action::Preserve,
        ] {
            assert_eq!(Action::from_canonical_str(value.as_str()), Some(value));
        }
        for value in [
            ConflictTier::None,
            ConflictTier::ClassPriority,
            ConflictTier::RulePriority,
            ConflictTier::Score,
            ConflictTier::SpanLength,
            ConflictTier::Validator,
            ConflictTier::SameClassContainment,
            ConflictTier::ValidatorVeto,
            ConflictTier::CollisionPolicy,
            ConflictTier::AnchoredContext,
            ConflictTier::StructuredContainment,
            ConflictTier::ContainmentPrecedence,
            ConflictTier::ProtectionOverride,
            ConflictTier::RecognizerId,
            ConflictTier::Merged,
            ConflictTier::Redact,
            ConflictTier::Resolve,
            ConflictTier::Fallback,
            ConflictTier::ManifestSweep,
        ] {
            assert_eq!(
                ConflictTier::from_canonical_str(value.as_str()),
                Some(value)
            );
        }
        for value in [DocumentKind::Structured, DocumentKind::Text] {
            assert_eq!(
                DocumentKind::from_canonical_str(value.as_str()),
                Some(value)
            );
        }
        for value in [
            FallbackReason::OverlapConflict,
            FallbackReason::ValidatorVeto,
            FallbackReason::AnchorMissing,
            FallbackReason::ResidualSuspect,
        ] {
            assert_eq!(
                FallbackReason::from_canonical_str(value.as_str()),
                Some(value)
            );
        }
    }

    #[test]
    fn redaction_log_error_display_is_stable() {
        assert_eq!(
            RedactionLogError::Sqlite("write failed".to_string()).to_string(),
            "sqlite redaction log error: write failed"
        );
        assert_eq!(
            RedactionLogError::Backend("sink failed".to_string()).to_string(),
            "backend redaction log error: sink failed"
        );
    }

    #[test]
    fn redaction_logger_trait_object_is_send_sync() {
        assert_send_sync::<dyn RedactionLogger>();
    }

    #[test]
    fn local_logger_can_implement_redaction_logger() {
        let logger = CapturingLogger;
        let entry = RedactionEntry {
            source: "unit-test".to_string(),
            recognizer_id: None,
            recognizer_version_id: None,
            class: PiiClass::Email,
            action: Action::Tokenize,
            field_name: None,
            document_kind: DocumentKind::Text,
            conflict_loser: false,
            decided_by: ConflictTier::None,
            created_at: 0,
            session_id: None,
            validator_fail_reason: None,
            labelled_value_scan_reason: None,
            ambiguity_record: None,
            collision_family: None,
            collision_variant: None,
            fallback_triggered: None,
            provenance_stage: None,
            provenance_model_id: None,
            provenance_model_version: None,
            provenance_artifact_sha256: None,
            provenance_tokenizer_sha256: None,
            provenance_locale_resolved: None,
            provenance_locale_match_kind: None,
            provenance_canonical_class: None,
            provenance_native_class: None,
            provenance_confidence: None,
            provenance_merged_from: None,
            backend_silently_dropped: None,
            restore_policy: None,
            restore_decision: None,
            restore_unknown_token_count: None,
            restore_manifest_bypass_count: None,
            restore_fresh_pii_count: None,
            restore_phase_mask: None,
            restore_trap_shape_count: None,
        };

        let trait_object: &dyn RedactionLogger = &logger;
        trait_object.log(&entry).expect("log entry");
    }

    #[test]
    fn redaction_entry_json_shape_omits_absent_recognizer_lineage() {
        let entry = RedactionEntry::new(
            "email.global",
            PiiClass::Email,
            Action::Tokenize,
            None,
            DocumentKind::Text,
            false,
            ConflictTier::None,
            0,
            None,
        );

        let rendered = serde_json::to_string(&entry).expect("serialize redaction entry");

        assert_eq!(
            rendered,
            r#"{"source":"email.global","class":"email","action":"tokenize","field_name":null,"document_kind":"text","conflict_loser":false,"decided_by":"none","created_at":0,"session_id":null,"validator_fail_reason":null,"ambiguity_record":null,"collision_family":null,"collision_variant":null,"fallback_triggered":null}"#
        );
    }

    #[test]
    fn redaction_entry_json_shape_includes_recognizer_lineage_when_present() {
        let entry = RedactionEntry::new(
            "ner/ort",
            PiiClass::Name,
            Action::Tokenize,
            None,
            DocumentKind::Text,
            false,
            ConflictTier::None,
            0,
            None,
        )
        .with_recognizer_metadata(
            Some("ner".to_string()),
            Some("ner.davlan-mbert.v1".to_string()),
        );

        let value: serde_json::Value =
            serde_json::to_value(&entry).expect("serialize redaction entry");

        assert_eq!(value["recognizer_id"], "ner");
        assert_eq!(value["recognizer_version_id"], "ner.davlan-mbert.v1");
    }

    #[test]
    fn candidate_keeps_versioned_and_unversioned_recognizer_ids() {
        let unversioned = Candidate::new(
            0..5,
            PiiClass::Email,
            "email.global",
            0.9,
            10,
            None,
            "email",
            "email.global",
            ConflictTier::None,
            Vec::new(),
        );
        assert_eq!(unversioned.recognizer_id, "email.global");
        assert_eq!(unversioned.recognizer_version_id, None);

        let versioned = unversioned
            .clone()
            .with_recognizer_version_id("email.global.v1");
        assert_eq!(versioned.recognizer_id, "email.global");
        assert_eq!(
            versioned.recognizer_version_id.as_deref(),
            Some("email.global.v1")
        );
    }
}

#[cfg(test)]
mod safety_net_manifest_tests {
    use super::*;

    fn span(start: usize, end: usize, class: PiiClass) -> EmittedTokenSpan {
        EmittedTokenSpan::new(start..end, start..end, class)
    }

    fn diff(manifest: Manifest, suspect: Range<usize>, class: PiiClass) -> Option<LeakKind> {
        manifest.diff_against(&suspect, &class)
    }

    #[test]
    fn exact_same_class_coverage_is_not_a_leak() {
        let manifest = Manifest::from_spans(vec![span(0, 8, PiiClass::Email)]);

        assert_eq!(diff(manifest, 0..8, PiiClass::Email), None);
    }

    #[test]
    fn uncovered_outside_all_tokens_is_uncovered() {
        let manifest = Manifest::from_spans(vec![span(20, 30, PiiClass::Email)]);

        assert_eq!(
            diff(manifest, 0..10, PiiClass::Email),
            Some(LeakKind::Uncovered)
        );
    }

    #[test]
    fn single_internal_gap_returns_partial_bleed() {
        let manifest = Manifest::from_spans(vec![
            span(0, 5, PiiClass::Email),
            span(10, 15, PiiClass::Email),
        ]);

        assert_eq!(
            diff(manifest, 0..15, PiiClass::Email),
            Some(LeakKind::PartialBleed { uncovered: 5..10 })
        );
    }

    #[test]
    fn multi_gap_returns_deterministic_first_uncovered_gap() {
        let manifest = Manifest::from_spans(vec![
            span(0, 3, PiiClass::Email),
            span(5, 7, PiiClass::Email),
            span(9, 12, PiiClass::Email),
        ]);

        // The first-gap-only rule is intentional for v0.6.1; full gap
        // enumeration is deferred until the report format can carry it.
        assert_eq!(
            diff(manifest, 0..12, PiiClass::Email),
            Some(LeakKind::PartialBleed { uncovered: 3..5 })
        );
    }

    #[test]
    fn multi_class_overlap_reports_first_mismatch_deterministically() {
        let manifest = Manifest::from_spans(vec![
            span(0, 4, PiiClass::Name),
            span(4, 8, PiiClass::Location),
        ]);

        assert_eq!(
            diff(manifest, 0..8, PiiClass::Email),
            Some(LeakKind::ClassMismatch {
                pipeline_class: PiiClass::Name,
                safety_net_class: PiiClass::Email,
            })
        );
    }

    #[test]
    fn adjacent_same_class_tokens_cover_continuously() {
        let manifest = Manifest::from_spans(vec![
            span(0, 5, PiiClass::Email),
            span(5, 10, PiiClass::Email),
        ]);

        assert_eq!(diff(manifest, 0..10, PiiClass::Email), None);
    }

    #[test]
    fn partial_bleed_at_start_end_and_middle() {
        let manifest = Manifest::from_spans(vec![span(3, 8, PiiClass::Email)]);

        assert_eq!(
            diff(manifest.clone(), 0..8, PiiClass::Email),
            Some(LeakKind::PartialBleed { uncovered: 0..3 })
        );
        assert_eq!(
            diff(manifest.clone(), 3..10, PiiClass::Email),
            Some(LeakKind::PartialBleed { uncovered: 8..10 })
        );

        let with_gap = Manifest::from_spans(vec![
            span(0, 3, PiiClass::Email),
            span(6, 10, PiiClass::Email),
        ]);
        assert_eq!(
            diff(with_gap, 0..10, PiiClass::Email),
            Some(LeakKind::PartialBleed { uncovered: 3..6 })
        );
    }

    #[test]
    fn byte_indices_are_not_character_indices() {
        let text = "ID: 😀 <Email_1>";
        let token_start = text.find("<Email_1>").expect("token start");
        assert_eq!(token_start, 9, "emoji is four bytes, not one char");
        let manifest = Manifest::from_spans(vec![span(token_start, text.len(), PiiClass::Email)]);

        assert_eq!(
            diff(manifest, token_start..text.len(), PiiClass::Email),
            None
        );
    }

    #[test]
    fn empty_suspect_range_is_not_a_leak() {
        let manifest = Manifest::default();

        assert_eq!(diff(manifest, 3..3, PiiClass::Email), None);
    }

    #[test]
    fn safety_net_error_display_is_variant_specific_and_bytes_free() {
        let cases = [
            SafetyNetError::Unavailable {
                reason: "not configured".to_string(),
            }
            .to_string(),
            SafetyNetError::WeightsMissing {
                path: "/models/opf".to_string(),
            }
            .to_string(),
            SafetyNetError::ModelUnavailable {
                reason: "load failed".to_string(),
            }
            .to_string(),
            SafetyNetError::ModelIntegrityMismatch {
                expected: "e3b0c44298fc1c149afbf4c8996fb924".to_string(),
                actual: "4e07408562bedb8b60ce05c1decfe3ad".to_string(),
            }
            .to_string(),
            SafetyNetError::InputTooLarge {
                limit: 1024,
                actual: 2048,
            }
            .to_string(),
            SafetyNetError::Runtime {
                message: "timeout".to_string(),
            }
            .to_string(),
            SafetyNetError::InvalidOutput {
                message: "bad json".to_string(),
            }
            .to_string(),
        ];

        for rendered in cases {
            assert!(!rendered.contains("alice@example.invalid"));
        }
    }
}

/// Shared recognizer contract for locale-aware PII candidates.
pub trait Recognizer: Send + Sync {
    /// Stable recognizer identifier.
    fn id(&self) -> &str;
    /// PII class supported by this recognizer.
    fn supported_class(&self) -> &PiiClass;
    /// Every class this recognizer can emit. Multi-label recognizers override this.
    fn possible_classes(&self) -> Vec<PiiClass> {
        vec![self.supported_class().clone()]
    }
    /// Detects PII candidates in the supplied input and context.
    fn detect(
        &self,
        input: &str,
        ctx: &DetectContext<'_>,
    ) -> std::result::Result<Vec<Candidate>, DetectError>;
    /// Registry-only detection view that may include marked guard vetoes for audit.
    /// Direct callers of [`Self::detect`] receive accepted candidates only.
    fn detect_for_registry(
        &self,
        input: &str,
        ctx: &DetectContext<'_>,
    ) -> std::result::Result<Vec<Candidate>, DetectError> {
        self.detect(input, ctx)
    }
    /// Token family used for candidate token emission.
    fn token_family(&self) -> &str;
    /// Optional validator kind used by pre-resolver validator-veto.
    fn validator_kind(&self) -> Option<ValidatorKind> {
        None
    }
    /// What validator veto does when [`Self::validator_kind`] fails. Defaults to
    /// [`ValidatorOnFail::Veto`]; validator veto honours [`ValidatorOnFail::Record`] only for
    /// kinds where [`ValidatorKind::allows_recorded_failure`] holds.
    fn validator_on_fail(&self) -> ValidatorOnFail {
        ValidatorOnFail::Veto
    }
    /// Locales where this recognizer is active.
    fn locales(&self) -> &[LocaleTag] {
        &[LocaleTag::Global]
    }
    /// Interpretation of [`Self::locales`] for request eligibility.
    fn locale_basis(&self) -> LocaleBasis {
        LocaleBasis::Document
    }
    /// Whether [`Self::detect`] returns the same candidates for the same input whatever
    /// `ctx.locale_chain` holds.
    ///
    /// A document-basis recognizer is offered every locale-chain step it is active for. When
    /// this returns `true`, the registry calls `detect` once per document and reuses the result
    /// at later steps; span claiming across steps is unchanged. Return `true` only when the
    /// output ignores the step locale; the default `false` keeps one call per step.
    fn detect_is_locale_invariant(&self) -> bool {
        false
    }

    /// Run after ordinary recognizers when detection needs their raw candidates.
    fn requires_prior_candidates(&self) -> bool {
        false
    }

    /// What this recognizer's candidates rest on. The registry stamps it on every candidate
    /// the recognizer emits, overwriting [`Candidate::evidence`]. Defaults to
    /// [`EvidenceKind::Learned`], which the repeat-value sweep never propagates; see
    /// [`EvidenceKind`].
    fn evidence(&self) -> EvidenceKind {
        EvidenceKind::Learned
    }
}

/// Caller-visible recognizer detection failure.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum DetectError {
    /// A recognizer backend failed while scanning the input.
    #[error("recognizer {recognizer_id} backend failed: {message}")]
    Backend {
        /// Stable recognizer identifier.
        recognizer_id: String,
        /// Sanitized backend error message.
        message: String,
    },
}

impl DetectError {
    /// Build a backend failure without requiring recognizer crates in `gaze-types`.
    pub fn backend(recognizer_id: impl Into<String>, source: impl Into<String>) -> Self {
        Self::Backend {
            recognizer_id: recognizer_id.into(),
            message: source.into(),
        }
    }
}

/// Candidate PII span emitted by a recognizer before final conflict resolution.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct Candidate {
    /// Byte span in the original input.
    pub span: Range<usize>,
    /// PII class assigned to the span.
    pub class: PiiClass,
    /// Recognizer identifier.
    pub recognizer_id: String,
    /// Optional versioned recognizer identifier for audit lineage.
    pub recognizer_version_id: Option<String>,
    /// Recognizer confidence score.
    pub score: f32,
    /// Rule or recognizer priority.
    pub priority: i32,
    /// Optional canonical representation for validation/merge logic.
    pub canonical_form: Option<String>,
    /// Token family used for output token shape.
    pub token_family: String,
    /// Candidate source label.
    pub source: String,
    /// Conflict tier that decided this candidate.
    pub decided_by: ConflictTier,
    /// Sources merged into this candidate.
    pub merged_sources: Vec<String>,
    /// Original recognizer IDs contributing to this candidate's provenance.
    pub source_recognizer_ids: Vec<String>,
    /// What the candidate rests on. [`Candidate::new`] starts at [`EvidenceKind::Learned`];
    /// the registry overwrites it with the emitting recognizer's [`Recognizer::evidence`].
    pub evidence: EvidenceKind,
    /// Set when validator veto kept the candidate although its validator failed
    /// ([`ValidatorOnFail::Record`]); written on the winner's audit row.
    pub validator_fail_reason: Option<ValidatorFailReason>,
    /// Closed reason for a labelled value boundary or length limit.
    pub labelled_value_scan_reason: Option<LabelledValueScanReason>,
    /// End of the original labelled-value capture before extension, for cross-class trimming.
    pub labelled_value_capture_end: Option<usize>,
    /// The recognizer's match guard vetoed the original capture.
    pub regex_guard_rejected: bool,
}

impl Candidate {
    /// Builds a recognizer candidate.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        span: Range<usize>,
        class: PiiClass,
        recognizer_id: impl Into<String>,
        score: f32,
        priority: i32,
        canonical_form: Option<String>,
        token_family: impl Into<String>,
        source: impl Into<String>,
        decided_by: ConflictTier,
        merged_sources: Vec<String>,
    ) -> Self {
        let recognizer_id = recognizer_id.into();
        Self {
            span,
            class,
            source_recognizer_ids: vec![recognizer_id.clone()],
            recognizer_id,
            recognizer_version_id: None,
            score,
            priority,
            canonical_form,
            token_family: token_family.into(),
            source: source.into(),
            decided_by,
            merged_sources,
            evidence: EvidenceKind::Learned,
            validator_fail_reason: None,
            labelled_value_scan_reason: None,
            labelled_value_capture_end: None,
            regex_guard_rejected: false,
        }
    }

    /// Whether a validator passed on this candidate: it carries a canonical form and no recorded
    /// failure. A canonical form alone proves nothing: an IBAN or card kept by
    /// [`ValidatorOnFail::Record`] may carry its normalizer's canonical form. The resolver's
    /// evidence tiers and the repeat-value sweep both ask this.
    pub fn checksum_validated(&self) -> bool {
        self.canonical_form.is_some() && self.validator_fail_reason.is_none()
    }

    /// Returns this candidate with its evidence kind set.
    pub fn with_evidence(mut self, evidence: EvidenceKind) -> Self {
        self.evidence = evidence;
        self
    }

    /// Returns this candidate with a translated span.
    pub fn with_span(mut self, span: Range<usize>) -> Self {
        self.span = span;
        self
    }

    /// Returns this candidate with versioned recognizer lineage attached.
    pub fn with_recognizer_version_id(mut self, recognizer_version_id: impl Into<String>) -> Self {
        self.recognizer_version_id = Some(recognizer_version_id.into());
        self
    }
}

/// Context supplied to recognizers during detection.
#[non_exhaustive]
pub struct DetectContext<'a> {
    /// Active locale chain.
    pub locale_chain: &'a [LocaleTag],
    /// Active dictionary bundle.
    pub dictionaries: &'a DictionaryBundle,
    /// Reserved field-aware matching slot; intentionally unit in v0.5 Phase B.
    pub fields: &'a (),
    /// Whether a recognizer degraded due to unavailable optional capability.
    pub degraded: Cell<bool>,
    /// For each byte of the detection input, the byte range of the caller's source text it
    /// came from, when the input is a normalized view of that text. A recognizer may read it to
    /// see breaks normalization hid (a dropped ZERO WIDTH JOINER, fullwidth digits next to
    /// ASCII); `card.structural` does. `None` when the input is the source text itself.
    pub source_spans: Option<&'a [(usize, usize)]>,
    /// Raw candidates found by ordinary recognizers, available only to a recognizer that
    /// requests the post-floor pass. They have not passed validator veto or conflict resolution.
    pub prior_candidates: Option<&'a [Candidate]>,
}

impl<'a> DetectContext<'a> {
    /// Builds detection context for a recognizer pass.
    pub fn new(locale_chain: &'a [LocaleTag], dictionaries: &'a DictionaryBundle) -> Self {
        Self {
            locale_chain,
            dictionaries,
            fields: &(),
            degraded: Cell::new(false),
            source_spans: None,
            prior_candidates: None,
        }
    }

    /// Records the source span of every input byte; see [`DetectContext::source_spans`].
    pub fn with_source_spans(mut self, source_spans: &'a [(usize, usize)]) -> Self {
        self.source_spans = Some(source_spans);
        self
    }

    pub fn with_prior_candidates(mut self, candidates: &'a [Candidate]) -> Self {
        self.prior_candidates = Some(candidates);
        self
    }
}

fn ensure_global(tags: &mut Vec<LocaleTag>) {
    if !tags.contains(&LocaleTag::Global) {
        tags.push(LocaleTag::Global);
    }
}

fn is_bcp47_parseable(raw: &str) -> bool {
    let mut parts = raw.split('-');
    let Some(language) = parts.next() else {
        return false;
    };
    if !(2..=8).contains(&language.len()) || !language.chars().all(|ch| ch.is_ascii_alphabetic()) {
        return false;
    }
    parts.all(|part| {
        (2..=8).contains(&part.len()) && part.chars().all(|ch| ch.is_ascii_alphanumeric())
    })
}

fn canonical_other(raw: &str) -> String {
    let mut parts = raw.split('-');
    let language = parts.next().unwrap_or_default().to_ascii_lowercase();
    let rest = parts.map(|part| {
        if part.len() == 2 && part.chars().all(|ch| ch.is_ascii_alphabetic()) {
            part.to_ascii_uppercase()
        } else {
            part.to_ascii_lowercase()
        }
    });
    std::iter::once(language)
        .chain(rest)
        .collect::<Vec<_>>()
        .join("-")
}

#[cfg(test)]
mod emitted_token_origin_tests {
    use super::*;

    /// The exact JSON a whole-value span produced before `origin` existed.
    /// It is a byte-for-byte snapshot on purpose: this field is persisted in
    /// session snapshots and document-extension bundles, so a stored whole span
    /// must serialize identically after the field was added, or every existing
    /// file on disk changes meaning.
    const LEGACY_WHOLE_JSON: &str =
        r#"{"clean_span":{"start":0,"end":8},"raw_span":{"start":0,"end":12},"class":"Email"}"#;

    #[test]
    fn whole_spans_serialize_byte_identically_to_the_pre_origin_snapshot() {
        let span = EmittedTokenSpan::new(0..8, 0..12, PiiClass::Email);
        let json = serde_json::to_string(&span).unwrap();
        assert_eq!(
            json, LEGACY_WHOLE_JSON,
            "adding `origin` changed the on-disk form of an existing whole span"
        );
        assert!(!json.contains("origin"));
    }

    #[test]
    fn json_written_before_the_field_existed_reads_back_as_whole() {
        let span: EmittedTokenSpan = serde_json::from_str(LEGACY_WHOLE_JSON).unwrap();
        assert_eq!(span.origin, EmittedTokenOrigin::Whole);
        assert!(span.origin.is_whole());
        assert_eq!(span, EmittedTokenSpan::new(0..8, 0..12, PiiClass::Email));
    }

    #[test]
    fn fragments_serialize_explicitly_and_round_trip() {
        let fragment = EmittedTokenSpan::residual_fragment(12..18, 27..33, PiiClass::Email);
        let json = serde_json::to_string(&fragment).unwrap();
        assert!(
            json.contains(r#""origin":"residual_fragment""#),
            "a fragment must say so on the wire: {json}"
        );
        assert_eq!(
            serde_json::from_str::<EmittedTokenSpan>(&json).unwrap(),
            fragment
        );
        assert!(fragment.origin.is_residual_fragment());
        assert!(!fragment.origin.is_whole());
    }

    #[test]
    fn a_fragment_is_never_equal_to_the_same_geometry_as_a_whole() {
        // Consumers branch on this, so the distinction has to survive equality
        // and not collapse into "same span, same class".
        let whole = EmittedTokenSpan::new(12..18, 27..33, PiiClass::Email);
        let fragment = EmittedTokenSpan::residual_fragment(12..18, 27..33, PiiClass::Email);
        assert_ne!(whole, fragment);
    }
}

#[cfg(test)]
mod name_edge_tests {
    use super::{expand_to_word_edges, extend_over_name_joiners};

    fn grown(
        text: &str,
        part: &str,
        grow: fn(&str, std::ops::Range<usize>) -> std::ops::Range<usize>,
    ) -> String {
        let start = text.find(part).expect("part in text");
        text[grow(text, start..start + part.len())].to_string()
    }

    #[test]
    fn word_edges_take_the_whole_word_and_nothing_past_it() {
        assert_eq!(
            grown(
                "ping jorunn vasquez-ellery",
                "jorunn vas",
                expand_to_word_edges
            ),
            "jorunn vasquez"
        );
        assert_eq!(grown("x JORUNN y", "ORUNN", expand_to_word_edges), "JORUNN");
        assert_eq!(
            grown("Müllerstraße 5", "llerstr", expand_to_word_edges),
            "Müllerstraße"
        );
        assert_eq!(grown("a b", "a", expand_to_word_edges), "a");
        assert_eq!(expand_to_word_edges("abc", 5..9), 5..9);
    }

    #[test]
    fn joiners_take_glued_name_parts_on_either_side() {
        let grow = extend_over_name_joiners;
        assert_eq!(
            grown("ping vasquez-ellery now", "vasquez", grow),
            "vasquez-ellery"
        );
        assert_eq!(
            grown("ping ellery-vasquez now", "vasquez", grow),
            "ellery-vasquez"
        );
        assert_eq!(
            grown("Anna-Lena Kim-Park", "Lena Kim", grow),
            "Anna-Lena Kim-Park"
        );
        assert_eq!(grown("O'Brien said", "Brien", grow), "O'Brien");
        assert_eq!(
            grown("d\u{2019}Artagnan", "Artagnan", grow),
            "d\u{2019}Artagnan"
        );
    }

    #[test]
    fn joiners_refuse_possessives_digits_and_bare_joiners() {
        let grow = extend_over_name_joiners;
        assert_eq!(grown("Vasquez's desk", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("Vasquez\u{2019}s desk", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("Vasquez-2024", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("Vasquez-ab12", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("Vasquez - Ellery", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("Vasquez-", "Vasquez", grow), "Vasquez");
        assert_eq!(grown("1-Vasquez", "Vasquez", grow), "Vasquez");
    }
}