keyhog_core/

spec.rs

//! Detector specification: TOML-based pattern definitions with regex, keywords,
//! verification endpoints, and companion patterns.

// Debt bucket: 55 public items, each landed before the crate floor raised
// `missing_docs` to `warn`. Each is part of the public TOML schema and would
// benefit from a doc line; remove this allow once they all carry one.
#![allow(missing_docs)]

mod evidence;
pub(crate) mod load;
mod validate;

use std::fmt;

use serde::ser::Error as _;
use serde::{Deserialize, Serialize};

pub use evidence::{ProviderEvidenceRole, ProviderEvidenceSensitivity};
pub use load::{
    load_detector_corpus, load_detectors, read_detector_toml_file, LoadedDetectorCorpus, SpecError,
    DETECTOR_TOML_FILE_BYTES,
};
pub use validate::{validate_detector, QualityIssue};

/// Metadata field specification for verification results.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MetadataSpec {
    /// Field name in the finding metadata map. Top-level verification metadata
    /// must name a supported [`ProviderEvidenceRole`]. Multi-step extraction
    /// may use a flow-local template name instead.
    pub name: String,
    /// `$`-rooted response selector, such as `$.account.email` or `$.orgs[0].name`.
    pub json_path: String,
    /// How a selected provider value may cross the reporting boundary.
    #[serde(default)]
    pub sensitivity: ProviderEvidenceSensitivity,
}

/// A complete detector definition loaded from a TOML file.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct DetectorSpec {
    /// Unique stable identifier (e.g. \`aws-access-key\`).
    pub id: String,
    /// Human-readable name.
    pub name: String,
    /// Target service (e.g. \`aws\`, \`stripe\`).
    pub service: String,
    /// Default severity for findings.
    pub severity: Severity,
    /// What scan phase produces this detector's findings, and thus what the
    /// loader requires of it. Defaults to [`DetectorKind::Regex`]. A `regex`
    /// detector carries >=1 regex pattern and fires in phase 1. A
    /// `phase2-generic` detector is a shapeless-secret bridge: bare passwords
    /// and high-entropy blobs fire in phase 2 from `keywords` plus
    /// `entropy_floor`. It may also declare structured regex envelopes while
    /// keeping both paths under one detector owner. Modeled here so those
    /// detectors are first-class TOML specs, one home for every knob, instead
    /// of engine constants scattered across `detector_ids.rs` and policy files.
    #[serde(default)]
    pub kind: DetectorKind,
    /// Detector-owned policy for model scoring. The model implementation is a
    /// shared engine, but whether this detector invokes it, how model and
    /// structural evidence combine, and how much source context is extracted
    /// are properties of the secret type and therefore live in its TOML.
    /// TOML detectors must declare it. Programmatic `DetectorSpec::default()`
    /// disables both model paths until the caller chooses a policy.
    pub ml: DetectorMlPolicySpec,
    /// Detector-owned scoring policy for regex matches. Every signal weight,
    /// entropy tier, penalty, structural floor, and low-promise result is
    /// compiled into the detector execution plan.
    #[serde(default)]
    pub match_confidence: Option<DetectorMatchConfidenceSpec>,
    /// Detector-owned offline validation policy. Each entry declares both the
    /// validator primitive and every detector-specific parameter it needs.
    /// Shared scanner code supplies the primitive implementations, but it must
    /// not own token prefixes, field widths, confidence floors, or shape rules.
    #[serde(default)]
    pub validators: Vec<DetectorValidatorSpec>,
    /// Detector-owned admission policy for asymmetric evasion transforms.
    /// Shared decoders implement reverse and Caesar recovery, while each
    /// detector declares the literal prefixes that make those transforms
    /// eligible. Empty lists disable the corresponding transform for this
    /// detector. The compiled scanner unions only the declarations in its
    /// active corpus, so a custom corpus never inherits unrelated prefixes.
    #[serde(default)]
    pub decode_transforms: DetectorDecodeTransformSpec,
    /// List of regex patterns to match. Defaults to empty so a
    /// `kind = "phase2-generic"` detector can omit it when it has no structured
    /// envelope; a `kind = "regex"` detector with no patterns is rejected by
    /// the quality gate (`validate_patterns_present`), so this default never
    /// silently ships a dead regex detector.
    #[serde(default)]
    pub patterns: Vec<PatternSpec>,
    /// Secondary patterns required to confirm a match.
    #[serde(default)]
    pub companions: Vec<CompanionSpec>,
    /// Live verification configuration.
    pub verify: Option<VerifySpec>,
    /// High-performance pre-filtering keywords.
    #[serde(default)]
    pub keywords: Vec<String>,
    /// Literal prefixes eligible for the optional `simdsieve` first-pass
    /// accelerator. Each prefix must be non-empty ASCII, unique in the loaded
    /// corpus, and an actual literal prefix of one of this detector's patterns.
    /// Empty means this detector does not participate in that accelerator.
    #[serde(default)]
    pub simdsieve_prefixes: Vec<String>,
    /// Self-declared per-detector confidence floor, in `[0.0, 1.0]`.
    ///
    /// When set, findings from THIS detector use this floor instead of the
    /// global `--min-confidence` / `[scan].min_confidence`. A detector with a
    /// distinctive vendor prefix (e.g. sourcegraph `sgp_<40hex>`, cursor
    /// `key_<64hex>`) is high-confidence by virtue of the prefix even when the
    /// body is low-entropy hex that the generic confidence model scores below
    /// the global floor; the detector author declares that here so the
    /// detector ships working out of the box. Costs nothing at scan time
    /// it is a single O(1) map lookup at the post-scan floor gate, on an
    /// already-compiled corpus. An operator `.keyhog.toml`
    /// `[detector.<id>] min_confidence` still overrides this self-declared
    /// default. `None` (the default) means "use the global floor".
    #[serde(default)]
    pub min_confidence: Option<f64>,
    /// Per-detector low-entropy suppression floor, owned HERE in the detector's
    /// own TOML, the single source of truth for generic and weak-anchor entropy
    /// gates (there is no separate `rules/entropy-floors.toml`, no code table,
    /// no cross-detector policy borrowing). Length-bucketed: the FIRST bucket whose
    /// `max_len >= L` sets the floor for a candidate of length `L`; the last
    /// bucket omits `max_len` and is the catch-all. `max_len` must strictly
    /// increase. A generic-detector candidate whose Shannon entropy is BELOW the
    /// applicable floor is suppressed. Active entropy owners must declare at
    /// least one bucket.
    #[serde(default)]
    pub entropy_floor: Vec<EntropyFloorBucket>,
    // ── PER-DETECTOR RECALL/PRECISION KNOBS (migration 2026-07-07) ────────────
    // ARCHITECTURE LAW: there is NO global/overall entropy or recall/precision
    // gate applied uniformly to every candidate. EVERY threshold that affects
    // whether a candidate survives is a PER-DETECTOR field, OWNED HERE in the
    // detector's own TOML spec, exactly like `min_confidence`/`entropy_floor`
    // above. Optional representation preserves schema compatibility for
    // non-owning programmatic detectors, but active entropy owners must declare
    // every field and are compiled into concrete runtime policy. Reading two
    // places to understand one active detector's behavior is banned.
    /// Per-detector HIGH-entropy threshold (bits/byte), the keyword-independent
    /// bar. Active entropy owners must declare it.
    #[serde(default)]
    pub entropy_high: Option<f64>,
    /// Per-detector keyword-context (LOW) entropy threshold (bits/byte).
    /// Active entropy owners must declare it.
    #[serde(default)]
    pub entropy_low: Option<f64>,
    /// Per-detector VERY-high entropy threshold for keyword-free/isolated tokens.
    /// Active entropy owners must declare it.
    #[serde(default)]
    pub entropy_very_high: Option<f64>,
    /// Metadata used when this detector owns a synthetic entropy finding.
    /// Keeping the semantic class, emitted id, display name, and service beside
    /// the owning detector prevents scanner-side identity tables from drifting
    /// away from detector policy. Active entropy owners must declare it; a
    /// missing block is a compile-time configuration error, never a guessed
    /// scanner identity.
    #[serde(default)]
    pub entropy_fallback: Option<EntropyFallbackMetadata>,
    /// Detector-owned confidence tiers for synthetic entropy findings. The
    /// entropy engine supplies shared Shannon scoring, while each owning
    /// detector declares how that evidence maps to report confidence.
    #[serde(default)]
    pub entropy_fallback_confidence: Option<EntropyFallbackConfidenceSpec>,
    /// Detector-owned confidence policy for phase-two generic assignments.
    /// Context bases and evidence lifts compile with the detector that owns
    /// the assignment keyword.
    #[serde(default)]
    pub generic_assignment_confidence: Option<GenericAssignmentConfidenceSpec>,
    /// Corpus-level entropy roles owned by this detector. Roles make the
    /// shared entropy engine data-driven: it resolves keyword-free,
    /// isolated-bare, and unclaimed-keyword candidates from detector TOML
    /// instead of naming built-in detector IDs in scanner code. Each role may
    /// be claimed by at most one detector in a compiled corpus.
    #[serde(default)]
    pub entropy_roles: Vec<EntropyDetectionRole>,
    /// Per-detector keyword-free entropy threshold used for clearly sensitive
    /// paths. Active entropy owners must declare it; setting it lower than
    /// `entropy_very_high` is an explicit recall policy for files such as `.env`
    /// and secrets manifests, not a scanner-wide hidden discount.
    #[serde(default)]
    pub sensitive_path_entropy_very_high: Option<f64>,
    /// Detector-owned isolated entropy shapes. These are explicit structural
    /// exceptions to the broad keyword-free floor, such as a four-group
    /// lower-dash app password. Active entropy owners must declare the list.
    #[serde(default)]
    pub entropy_shapes: Vec<EntropyShapeSpec>,
    /// Complete detector-owned strict plausibility policy. Active entropy
    /// owners must declare the block; absence is valid only for detector paths
    /// that never invoke phase-2 plausibility scoring.
    #[serde(default)]
    pub plausibility: Option<DetectorPlausibilityPolicySpec>,
    /// Precedence when this detector owns entropy-fallback policy for one of
    /// its declared keywords. Active entropy owners must declare the value;
    /// regex detectors opt in by doing so. Higher values win overlapping
    /// keyword claims, so the policy decision is declared in detector TOML
    /// instead of depending on detector IDs or load order.
    #[serde(default)]
    pub entropy_policy_priority: Option<u16>,
    /// Per-detector BPE token-efficiency ceiling in UTF-8 bytes per
    /// `cl100k_base` token. Candidates above the ceiling are word-like and are
    /// suppressed after the cheaper entropy/shape gates. BPE-enabled entropy
    /// owners must declare it; an explicit scan override still has precedence.
    #[serde(default)]
    pub bpe_max_bytes_per_token: Option<f64>,
    /// Whether the BPE token-efficiency precision gate applies to this
    /// detector. Active entropy owners must declare the choice. `Some(false)`
    /// disables tokenization for detector families such as human-chosen
    /// passwords where word-like values are legitimate. A disabled detector
    /// must not also set a BPE ceiling.
    #[serde(default)]
    pub bpe_enabled: Option<bool>,
    /// Exact printable-hex character counts this phase-2 detector may retain
    /// after transport decoding. Keeping the lengths in detector TOML avoids a
    /// scanner-wide hardcoded key-width list. An empty list retains no decoded
    /// digest-shaped values.
    #[serde(default)]
    pub decoded_hex_key_material_lengths: Vec<usize>,
    /// Detector-owned canonical pure-hex key material. Phase-2 generic
    /// detectors scope lengths to exact assignment `keywords` or vendor
    /// `suffixes`. Regex detectors use length-only entries because their own
    /// matched pattern is already the anchor. This keeps digest-shaped recall
    /// exceptions in detector TOML instead of a scanner-wide length table.
    #[serde(default)]
    pub canonical_hex_key_material: Vec<CanonicalHexKeyMaterialSpec>,
    /// Per-detector minimum length for an anchor-free (keyword-free/isolated)
    /// candidate. Active entropy owners must declare it.
    #[serde(default)]
    pub keyword_free_min_len: Option<usize>,
    /// Per-detector minimum candidate length in UTF-8 bytes (any candidate this
    /// detector emits). Active entropy owners must declare it.
    #[serde(default)]
    pub min_len: Option<usize>,
    /// Per-detector maximum byte length for generic assignment values owned by
    /// this entropy policy, including regex detectors that also claim generic
    /// keywords through `entropy_policy_priority`.
    /// Values above this ceiling are rejected whole; they are never truncated
    /// into an apparently valid credential. Active phase-2 entropy owners must
    /// declare it.
    #[serde(default)]
    pub max_len: Option<usize>,
    /// Structural assignment suffixes for `<vendor>_<suffix>` names not claimed
    /// by an exact keyword. At most one phase-2 generic detector may declare a
    /// non-empty list; omission disables unlisted vendor suffixes.
    #[serde(default)]
    pub generic_vendor_suffixes: Vec<String>,
    /// Optional suffix segments accepted after an exact assignment keyword.
    /// At most one phase-2 generic detector may declare a non-empty list.
    #[serde(default)]
    pub generic_assignment_tail_suffixes: Vec<String>,
    /// Per-detector path-exclusion regexes (betterleaks-style allowlist): a match
    /// whose FILE PATH matches any of these is suppressed. Owned per detector.
    #[serde(default)]
    pub allowlist_paths: Vec<String>,
    /// Per-detector value-exclusion regexes: a matched SECRET VALUE matching any
    /// of these is suppressed (per-detector test/example/placeholder demotion).
    #[serde(default)]
    pub allowlist_values: Vec<String>,
    /// Per-detector literal stopwords: a matched value equal to / containing any
    /// of these (case-insensitive) is suppressed. Owned per detector.
    #[serde(default)]
    pub stopwords: Vec<String>,
    /// Uppercase assignment-key fragments that identify public IDs rather than
    /// credentials for this detector's entropy path. Runtime matching is ASCII
    /// case-insensitive without allocating a normalized source line, so boundary
    /// bytes such as `=`, `:`, space, and quote are semantic. An empty list
    /// disables this detector-local suppression. TOML stores canonical uppercase.
    #[serde(default)]
    pub public_identifier_assignment_markers: Vec<String>,
    /// Per-detector "structural password slot" classification, OWNED HERE per the
    /// architecture law above (was a hardcoded detector-id list in scanner
    /// code, so a detector's family lived outside its TOML).
    ///
    /// `true` marks a STRONG-anchor detector whose regex proves a syntactic
    /// credential SLOT (`scheme://user:<x>@host`, `IDENTIFIED BY '<x>'`,
    /// `--password <x>`, `Bearer <x>`) but captures a FREE-FORM value the way a
    /// real password is written. Such detectors apply the password-slot
    /// placeholder gate (drop a captured literal dictionary word like `password`
    /// / `secret`, or a low-letter-diversity mask like `xxxxxxxx`) that a
    /// service-anchored detector's structured capture never needs. A new
    /// structural-password-slot detector now declares this in its own TOML, no
    /// code edit (and the whole story lives in the detector file).
    #[serde(default)]
    pub structural_password_slot: bool,
    /// Per-detector weak-anchor classification, owned by this detector definition.
    ///
    /// `true` marks a SERVICE-anchored detector whose regex capture nonetheless
    /// structurally collides with a generic value (a bare hex/base64 run the
    /// vendor prefix does not tightly bound: `alchemy-api-key`, `carbon-black-api-key`,
    /// `flickr-api-key`, …), so scanner suppression keeps the Tier-B shape gates
    /// ENGAGED for it (`WeakAnchorBase::Always`) instead of trusting the anchor.
    /// Without this the collision-prone captures would bypass the generic
    /// shape/entropy floors and flood FP. The structural-password-slot family is
    /// deliberately NOT weak_anchor (its slot is syntactic, not a vendor prefix).
    /// A new weak-anchor detector now declares this in its own TOML, no code
    /// edit (and the whole story lives in the detector file).
    #[serde(default)]
    pub weak_anchor: bool,
    /// Per-detector private-key-block classification, owned by this detector
    /// definition.
    ///
    /// `true` marks a detector whose match SPAN is an enclosing private-key block
    /// (`private-key`, `ssh-private-key`, `github-app-private-key`), a multi-line
    /// PEM/OpenSSH body. Resolution (`resolution::suppress_matches_nested_in_private_key_blocks`)
    /// fully suppresses any lower-specificity child finding nested inside such a
    /// span (an entropy/base64 hit on a line INSIDE the key body is not a second
    /// secret). A new private-key-block detector now declares this in its own TOML
    /// no code edit (and the whole story lives in the detector file).
    #[serde(default)]
    pub private_key_block: bool,
    /// Explicit detector specificity used when overlapping findings compete.
    ///
    /// Higher values win. The default `0` preserves equal standing; detectors
    /// that intentionally wrap a broader detector declare their precedence here
    /// instead of relying on detector ID spelling or input order.
    #[serde(default)]
    pub resolution_priority: i16,
    /// Per-detector credential shape constraint (see [`CredentialShape`]), OWNED
    /// HERE per the architecture law (was `rules/detector-credential-shapes.toml`).
    /// `None` (the default) means the detector declares no shape constraint.
    #[serde(default)]
    pub credential_shape: Option<CredentialShape>,
    /// Inline self-test fixtures (`[[detector.tests]]`, Tier-B data): each entry
    /// carries a positive example the detector MUST fire on and/or a negative
    /// example it MUST NOT. Consumed by the contract/self-validate harness;
    /// ignored at scan time. Modeled here (rather than silently dropped) so the
    /// schema's `deny_unknown_fields` typo-guard covers the whole detector file.
    #[serde(default)]
    pub tests: Vec<DetectorTestSpec>,
}

/// Which scan phase produces a detector's findings (see [`DetectorSpec::kind`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DetectorKind {
    /// Phase-1 regex detector: carries >=1 regex pattern, has a distinctive
    /// anchor. The default and the vast majority of the corpus.
    #[default]
    Regex,
    /// Phase-2 generic bridge: fires on `keywords` + `entropy_floor`. It may
    /// additionally carry explicit regex patterns for strongly structured
    /// envelopes (for example a JSON `"secret"` field); those anchors compile
    /// through the same detector while phase-2 remains the shapeless fallback.
    Phase2Generic,
}

/// Literal admission prefixes for detector-owned evasion recovery.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorDecodeTransformSpec {
    /// Plaintext prefixes whose character-reversed spelling may admit reverse
    /// recovery. Prefixes shorter than three bytes are rejected because they
    /// create excessive accidental matches in encoded data.
    #[serde(default)]
    pub reverse_prefixes: Vec<String>,
    /// Plaintext prefixes whose rotated spellings may admit Caesar/ROT-N
    /// recovery. A prefix must contain at least one ASCII letter so rotation
    /// can change it.
    #[serde(default)]
    pub caesar_prefixes: Vec<String>,
}

impl DetectorDecodeTransformSpec {
    /// Validate transform prefix shape and per-list uniqueness.
    pub fn validate(&self) -> Vec<String> {
        let mut issues = Vec::new();
        validate_decode_transform_prefixes(
            "reverse_prefixes",
            &self.reverse_prefixes,
            true,
            &mut issues,
        );
        validate_decode_transform_prefixes(
            "caesar_prefixes",
            &self.caesar_prefixes,
            false,
            &mut issues,
        );
        issues
    }
}

fn validate_decode_transform_prefixes(
    field: &str,
    prefixes: &[String],
    reverse: bool,
    issues: &mut Vec<String>,
) {
    let mut seen = std::collections::HashSet::with_capacity(prefixes.len());
    for prefix in prefixes {
        if prefix.is_empty() || !prefix.is_ascii() {
            issues.push(format!("{field} entry {prefix:?} must be non-empty ASCII"));
            continue;
        }
        if reverse && prefix.len() < 3 {
            issues.push(format!(
                "{field} entry {prefix:?} must contain at least three bytes"
            ));
        }
        if !reverse && !prefix.bytes().any(|byte| byte.is_ascii_alphabetic()) {
            issues.push(format!(
                "{field} entry {prefix:?} must contain an ASCII letter"
            ));
        }
        if !seen.insert(prefix.as_str()) {
            issues.push(format!("{field} contains duplicate prefix {prefix:?}"));
        }
    }
}

/// How the shared ML model participates in one detector path.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DetectorMlMode {
    /// Do not run model inference for this path.
    #[default]
    Disabled,
    /// Let the model raise structurally derived confidence but never veto a
    /// detector match. The detector-owned weight controls the fraction of the
    /// positive model delta that is applied.
    Lift,
    /// Combine model confidence with the detector's structural evidence.
    Blend,
    /// Let the model score replace the heuristic score for weakly anchored
    /// candidates where entropy magnitude is not positive evidence.
    Authoritative,
}

impl DetectorMlMode {
    /// Stable TOML spelling used by diagnostics and semantic hashes.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Disabled => "disabled",
            Self::Lift => "lift",
            Self::Blend => "blend",
            Self::Authoritative => "authoritative",
        }
    }
}

/// Complete detector-local configuration for the shared ML scoring engine.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorMlPolicySpec {
    /// Policy for regex and generic-assignment matches owned by this detector.
    pub match_mode: DetectorMlMode,
    /// Policy for entropy-fallback candidates owned by this detector.
    pub entropy_mode: DetectorMlMode,
    /// Model contribution for `lift` and `blend`, in the closed interval `[0, 1]`.
    pub weight: f64,
    /// Number of source lines on each side of the candidate supplied to feature
    /// extraction. Zero intentionally restricts inference to the candidate line.
    pub context_radius_lines: usize,
}

/// Complete detector-local confidence policy for regex candidates.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorMatchConfidenceSpec {
    /// Weight earned by a detector-specific literal prefix.
    pub literal_prefix_weight: f64,
    /// Weight earned by a required contextual capture.
    pub context_anchor_weight: f64,
    /// Full weight earned at the very-high entropy tier.
    pub entropy_weight: f64,
    /// Partial weight earned at the resolved high entropy tier.
    pub high_entropy_partial_weight: f64,
    /// Shannon threshold for moderate entropy evidence.
    pub moderate_entropy_threshold: f64,
    /// Weight earned at the moderate entropy tier.
    pub moderate_entropy_weight: f64,
    /// Shannon floor below which a long match receives a penalty.
    pub low_entropy_penalty_floor: f64,
    /// Minimum byte length above which the low-entropy penalty applies.
    pub low_entropy_min_match_length: usize,
    /// Multiplier applied when the low-entropy penalty fires.
    pub low_entropy_penalty_multiplier: f64,
    /// Weight earned when detector-owned context is nearby.
    pub keyword_nearby_weight: f64,
    /// Weight earned in a sensitive file.
    pub sensitive_file_weight: f64,
    /// Weight earned when a companion capture is present.
    pub companion_weight: f64,
    /// Margin above the resolved high tier for full entropy evidence.
    pub very_high_entropy_margin: f64,
    /// Structural floor for a non-generic match carrying a compiled anchor.
    pub named_anchor_floor: Option<f64>,
    /// Final score for an unaccompanied generic match rejected by the cheap
    /// promise gate before model inference.
    pub low_promise_confidence: Option<f64>,
    /// Confidence multiplier for an assignment context.
    pub assignment_context_multiplier: f64,
    /// Confidence multiplier for a string-literal context.
    pub string_literal_context_multiplier: f64,
    /// Confidence multiplier when source context is unknown.
    pub unknown_context_multiplier: f64,
    /// Confidence multiplier for documentation context.
    pub documentation_context_multiplier: f64,
    /// Confidence multiplier for comment context.
    pub comment_context_multiplier: f64,
    /// Confidence multiplier for test-code context.
    pub test_context_multiplier: f64,
    /// Confidence multiplier for encrypted or sealed context.
    pub encrypted_context_multiplier: f64,
    /// Hard-suppression threshold for comment, test, and documentation context.
    pub soft_context_suppression_threshold: f64,
    /// Hard-suppression threshold for encrypted or sealed context.
    pub encrypted_context_suppression_threshold: f64,
    /// Detector-owned policy applied after optional model scoring.
    pub post_match: DetectorPostMatchConfidenceSpec,
}

/// Detector-local confidence penalties applied after optional model scoring.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorPostMatchConfidenceSpec {
    /// Multiplier for a surface or decoded placeholder word.
    pub placeholder_multiplier: f64,
    /// Minimum unique-byte ratio before the value receives a diversity penalty.
    pub minimum_byte_diversity: f64,
    /// Multiplier for values below `minimum_byte_diversity`.
    pub low_diversity_multiplier: f64,
    /// Maximum repeated-byte run ratio before the value receives a penalty.
    pub maximum_repeat_ratio: f64,
    /// Absolute repeated-byte run length that receives a penalty regardless of ratio.
    pub degenerate_run_min_length: usize,
    /// Multiplier for values exceeding either repeated-byte limit.
    pub degenerate_repeat_multiplier: f64,
    /// Multiplier for decoded data envelopes. Omit it when the detector's
    /// anchored credential shape makes this evidence inapplicable.
    pub data_envelope_multiplier: Option<f64>,
    /// Multiplier for findings under fixture or example path components.
    pub fixture_path_multiplier: f64,
    /// Reapply the source-context multiplier to model scores below this floor.
    pub ml_context_reapply_below: f64,
}

impl DetectorPostMatchConfidenceSpec {
    /// Validate ratios, multipliers, and the repeated-run boundary.
    pub fn validate(self) -> Result<(), &'static str> {
        if [
            self.placeholder_multiplier,
            self.minimum_byte_diversity,
            self.low_diversity_multiplier,
            self.maximum_repeat_ratio,
            self.degenerate_repeat_multiplier,
            self.fixture_path_multiplier,
            self.ml_context_reapply_below,
        ]
        .into_iter()
        .chain(self.data_envelope_multiplier)
        .any(|value| !value.is_finite() || !(0.0..=1.0).contains(&value))
        {
            return Err("post-match ratios and multipliers must be finite values in [0.0, 1.0]");
        }
        if self.degenerate_run_min_length == 0 {
            return Err("post-match degenerate_run_min_length must be greater than zero");
        }
        Ok(())
    }
}

impl DetectorMatchConfidenceSpec {
    /// Validate probabilities, entropy domains, and evidence ordering.
    pub fn validate(self) -> Result<(), &'static str> {
        self.post_match.validate()?;
        let probabilities = [
            self.literal_prefix_weight,
            self.context_anchor_weight,
            self.entropy_weight,
            self.high_entropy_partial_weight,
            self.moderate_entropy_weight,
            self.low_entropy_penalty_multiplier,
            self.keyword_nearby_weight,
            self.sensitive_file_weight,
            self.companion_weight,
            self.assignment_context_multiplier,
            self.string_literal_context_multiplier,
            self.unknown_context_multiplier,
            self.documentation_context_multiplier,
            self.comment_context_multiplier,
            self.test_context_multiplier,
            self.encrypted_context_multiplier,
            self.soft_context_suppression_threshold,
            self.encrypted_context_suppression_threshold,
        ];
        if probabilities
            .into_iter()
            .chain(self.named_anchor_floor)
            .chain(self.low_promise_confidence)
            .any(|value| !value.is_finite() || !(0.0..=1.0).contains(&value))
        {
            return Err("weights, multipliers, floors, and final scores must be finite values in [0.0, 1.0]");
        }
        if [
            self.moderate_entropy_threshold,
            self.low_entropy_penalty_floor,
            self.very_high_entropy_margin,
        ]
        .into_iter()
        .any(|value| !value.is_finite() || !(0.0..=u8::BITS as f64).contains(&value))
        {
            return Err("entropy thresholds and margins must be finite values in [0.0, 8.0]");
        }
        if self.low_entropy_penalty_floor > self.moderate_entropy_threshold {
            return Err("low_entropy_penalty_floor must not exceed moderate_entropy_threshold");
        }
        if self.moderate_entropy_weight > self.high_entropy_partial_weight
            || self.high_entropy_partial_weight > self.entropy_weight
        {
            return Err("entropy weights must satisfy moderate <= high partial <= full");
        }
        if self.literal_prefix_weight
            + self.context_anchor_weight
            + self.entropy_weight
            + self.keyword_nearby_weight
            + self.sensitive_file_weight
            + self.companion_weight
            <= 0.0
        {
            return Err("at least one maximum signal weight must be positive");
        }
        Ok(())
    }
}

/// Exact base64 dialect accepted by a detector-owned offline validator.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DetectorBase64Alphabet {
    Standard,
    StandardNoPad,
    UrlSafe,
    UrlSafeNoPad,
}

/// An offline validator declared by one detector.
///
/// The enum is deliberately closed and typed: malformed combinations are
/// rejected while loading detector TOML instead of becoming runtime defaults.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case", deny_unknown_fields)]
pub enum DetectorValidatorSpec {
    /// CRC32 over a fixed entropy body, encoded as a fixed-width base62 suffix.
    Crc32Base62 {
        prefixes: Vec<String>,
        entropy_len: usize,
        checksum_len: usize,
        reject_overlong: bool,
        confidence_floor: f64,
    },
    /// GitHub fine-grained PAT CRC32 layout with two underscore-separated
    /// segments and compatibility for the two formats GitHub has emitted.
    GithubFineGrainedCrc32 {
        prefixes: Vec<String>,
        left_len: usize,
        right_len: usize,
        checksum_len: usize,
        confidence_floor: f64,
    },
    /// A base64 payload whose successful decode is offline authenticity
    /// evidence, such as the macaroon carried by a PyPI API token.
    Base64Payload {
        prefixes: Vec<String>,
        alphabet: DetectorBase64Alphabet,
        min_encoded_len: usize,
        max_encoded_len: usize,
        min_decoded_len: usize,
        confidence_floor: f64,
    },
    /// The detector's own patterns are the complete structural contract. The
    /// scanner compiles anchored copies once for generic/public validation;
    /// named matches reuse the already-proven pattern result without rerunning
    /// a second regex.
    PatternShape {
        prefixes: Vec<String>,
        /// Whether a candidate that begins with a complete declared pattern but
        /// continues with provider-token bytes is an unknown future shape
        /// (`true`) or malformed (`false`).
        allow_overlong: bool,
    },
}

impl DetectorValidatorSpec {
    /// Literal prefixes claimed by this validator.
    pub fn prefixes(&self) -> &[String] {
        match self {
            Self::Crc32Base62 { prefixes, .. }
            | Self::GithubFineGrainedCrc32 { prefixes, .. }
            | Self::Base64Payload { prefixes, .. }
            | Self::PatternShape { prefixes, .. } => prefixes,
        }
    }

    /// Confidence floor earned by positive offline proof, when applicable.
    pub fn confidence_floor(&self) -> Option<f64> {
        match self {
            Self::Crc32Base62 {
                confidence_floor, ..
            }
            | Self::GithubFineGrainedCrc32 {
                confidence_floor, ..
            }
            | Self::Base64Payload {
                confidence_floor, ..
            } => Some(*confidence_floor),
            Self::PatternShape { .. } => None,
        }
    }
}

/// Strict candidate-plausibility policy owned by one detector TOML.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorPlausibilityPolicySpec {
    /// Entropy floor for mixed alphabetic/numeric values.
    pub mixed_alnum_floor: f64,
    /// Entropy floor for symbolic values carrying a credential anchor.
    pub symbolic_entropy_floor: f64,
    /// Minimum entropy in the second half of a long value.
    pub second_half_entropy_floor: f64,
    /// Minimum byte length at which second-half entropy is required.
    pub second_half_min_len: usize,
    /// Minimum byte length at which distinct-character diversity is required.
    pub unique_chars_min_len: usize,
    /// Minimum distinct characters required at and above `unique_chars_min_len`.
    pub min_unique_chars: usize,
    /// Longest unanchored all-hex value that is not rejected as key material.
    pub unanchored_hex_max_len: usize,
    /// Longest single-character repetition that is not rejected.
    pub identical_char_max_len: usize,
    /// Minimum byte length for an isolated structured dotted token.
    pub structured_dotted_min_len: usize,
    /// Minimum byte length for the mixed alphabetic/numeric carve-out.
    pub mixed_alnum_min_len: usize,
    /// Shannon floor for isolated mixed-case alphanumeric tokens, with or
    /// without an underscore separator.
    pub isolated_mixed_entropy_floor: f64,
    /// Minimum byte length for isolated symbolic opaque-token shapes.
    pub isolated_symbolic_min_len: usize,
    /// Minimum number of symbol bytes in an isolated symbolic shape.
    pub isolated_symbolic_min_symbols: usize,
    /// Require at least one symbolic byte other than underscore.
    pub isolated_symbolic_requires_non_underscore: bool,
    /// Minimum number of symbol bytes in an isolated alpha-only symbolic shape.
    pub isolated_alpha_only_min_symbols: usize,
    /// Minimum fraction of bytes that must be alphabetic in an isolated
    /// alpha-only symbolic shape.
    pub isolated_alpha_only_min_alpha_ratio: f64,
    /// Minimum fraction of characters that must be alphanumeric.
    pub min_alnum_ratio: f64,
    /// Maximum byte length for a source type-name shape.
    pub source_type_name_max_len: usize,
    /// Minimum uppercase byte count for a source type-name shape.
    pub source_type_name_min_uppercase: usize,
    /// Minimum byte length at which a high-entropy punctuation payload may
    /// bypass URL and path-shape suppression.
    pub url_path_high_entropy_min_len: usize,
    /// Minimum byte length for the left component of `opaque:opaque` tokens.
    pub isolated_colon_left_min_len: usize,
    /// Minimum byte length for the right component of `opaque:opaque` tokens.
    pub isolated_colon_right_min_len: usize,
    /// Shannon floor for an unanchored leading-slash base64 token.
    pub leading_slash_base64_entropy_floor: f64,
    /// Minimum byte length for an unanchored leading-slash base64 token.
    pub leading_slash_base64_min_len: usize,
    /// Margin added to the Tier-A entropy threshold before comparing an
    /// unanchored keyword-free candidate. Required only for the detector that
    /// claims the `keyword-free` entropy role.
    #[serde(default)]
    pub keyword_free_operator_margin: Option<f64>,
    /// Reject periodic values, including a truncated final repetition.
    pub reject_repeated_blocks: bool,
    /// Admit an anchored alphabetic value after the other shape gates pass.
    pub allow_alphabetic_credential: bool,
    /// Reject source-language identifier shapes.
    pub reject_program_identifiers: bool,
    /// Reject mixed alphanumeric source-symbol shapes that include digits.
    pub reject_source_symbol_identifiers: bool,
    /// Reject dash-segmented product serial and identifier shapes.
    pub reject_dash_segmented_alnum: bool,
}

impl Default for DetectorMlPolicySpec {
    fn default() -> Self {
        Self {
            match_mode: DetectorMlMode::Disabled,
            entropy_mode: DetectorMlMode::Disabled,
            weight: 0.0,
            context_radius_lines: 0,
        }
    }
}

/// One length bucket of a detector's [`DetectorSpec::entropy_floor`]. Owned in the
/// detector's TOML (`entropy_floor = [{ max_len = 24, floor = 3.0 }, { floor = 3.5 }]`).
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct EntropyFloorBucket {
    /// Inclusive maximum candidate length this bucket applies to. Omit on the
    /// final catch-all bucket (applies to any longer candidate).
    #[serde(default)]
    pub max_len: Option<usize>,
    /// Shannon-entropy floor (bits/byte). A candidate scoring below this is
    /// suppressed by the low-entropy gate.
    pub floor: f64,
}

/// Detector-owned identity for a finding emitted by the entropy fallback path.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct EntropyFallbackMetadata {
    /// Semantic class used by the entropy fallback. This is detector data,
    /// not a scanner-side identity bucket; it keeps the emitted role visible
    /// when several custom detectors share the same generic family.
    pub class: EntropyFallbackClass,
    /// Stable emitted detector id. Must use the `entropy-` namespace.
    pub id: String,
    /// Human-readable finding name.
    pub name: String,
    /// Service family attached to the synthetic finding.
    pub service: String,
}

/// Confidence mapping for one detector's synthetic entropy findings.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct EntropyFallbackConfidenceSpec {
    /// Maximum base confidence below the detector's high-entropy tier.
    pub low_entropy_max: f64,
    /// Base confidence at or above `entropy_high`.
    pub high_entropy: f64,
    /// Base confidence at or above `entropy_very_high`.
    pub very_high_entropy: f64,
    /// Confidence added when a detector keyword owns the candidate.
    pub keyword_lift: f64,
    /// Maximum confidence this fallback path may emit.
    pub max_confidence: f64,
}

impl EntropyFallbackConfidenceSpec {
    /// Validate probability bounds and monotonic evidence tiers.
    pub fn validate(self) -> Result<(), &'static str> {
        let values = [
            self.low_entropy_max,
            self.high_entropy,
            self.very_high_entropy,
            self.keyword_lift,
            self.max_confidence,
        ];
        if values
            .into_iter()
            .any(|value| !value.is_finite() || !(0.0..=1.0).contains(&value))
        {
            return Err("all values must be finite probabilities in [0.0, 1.0]");
        }
        if self.low_entropy_max > self.high_entropy
            || self.high_entropy > self.very_high_entropy
            || self.very_high_entropy > self.max_confidence
        {
            return Err(
                "confidence tiers must satisfy low_entropy_max <= high_entropy <= very_high_entropy <= max_confidence",
            );
        }
        Ok(())
    }
}

/// Confidence mapping for a detector-owned generic assignment candidate.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GenericAssignmentConfidenceSpec {
    /// Base confidence for ordinary source and configuration content.
    pub ordinary_base: f64,
    /// Base confidence for test content when test-path penalties are enabled.
    pub test_base: f64,
    /// Base confidence for documentation when test-path penalties are enabled.
    pub documentation_base: f64,
    /// Base confidence for comments under the default comment policy.
    pub comment_base: f64,
    /// Base confidence for comments when the operator enables comment scanning.
    pub scanned_comment_base: f64,
    /// Shannon entropy at which the entropy lift starts.
    pub entropy_reference: f64,
    /// Confidence gained per entropy bit above `entropy_reference`.
    pub entropy_gain_per_bit: f64,
    /// Maximum confidence contributed by entropy.
    pub entropy_lift_max: f64,
    /// Byte length at which the length lift starts.
    pub length_reference: usize,
    /// Confidence gained per byte above `length_reference`.
    pub length_gain_per_byte: f64,
    /// Maximum confidence contributed by length.
    pub length_lift_max: f64,
    /// Maximum confidence this generic assignment path may emit.
    pub max_confidence: f64,
}

impl GenericAssignmentConfidenceSpec {
    /// Validate probability bounds and the byte-entropy reference domain.
    pub fn validate(self) -> Result<(), &'static str> {
        let probabilities = [
            self.ordinary_base,
            self.test_base,
            self.documentation_base,
            self.comment_base,
            self.scanned_comment_base,
            self.entropy_gain_per_bit,
            self.entropy_lift_max,
            self.length_gain_per_byte,
            self.length_lift_max,
            self.max_confidence,
        ];
        if probabilities
            .into_iter()
            .any(|value| !value.is_finite() || !(0.0..=1.0).contains(&value))
        {
            return Err(
                "bases, gains, lift caps, and max_confidence must be finite values in [0.0, 1.0]",
            );
        }
        if !self.entropy_reference.is_finite()
            || !(0.0..=u8::BITS as f64).contains(&self.entropy_reference)
        {
            return Err("entropy_reference must be finite and in [0.0, 8.0]");
        }
        if [
            self.ordinary_base,
            self.test_base,
            self.documentation_base,
            self.comment_base,
            self.scanned_comment_base,
        ]
        .into_iter()
        .any(|base| base > self.max_confidence)
        {
            return Err("every context base must be less than or equal to max_confidence");
        }
        Ok(())
    }
}

impl EntropyFallbackMetadata {
    /// Whether this metadata can safely identify a synthetic entropy finding.
    /// IDs stay lowercase and delimiter-stable so reports, hashes, and
    /// suppression receipts cannot acquire ambiguous namespace variants.
    pub fn has_valid_identity(&self) -> bool {
        let Some(suffix) = self.id.strip_prefix("entropy-") else {
            return false;
        };
        !suffix.is_empty()
            && suffix
                .bytes()
                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
            && !self.name.trim().is_empty()
            && !self.service.trim().is_empty()
    }
}

/// Semantic role of a detector-owned synthetic entropy finding.
///
/// The role is deliberately separate from the emitted id and display text:
/// operators may rename a detector's finding without changing which evidence
/// family owns the candidate. Runtime emission resolves the active detector's
/// complete metadata, so this enum never acts as a scanner-wide identity
/// fallback.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "kebab-case")]
pub enum EntropyFallbackClass {
    /// Anchor-free high-entropy material owned by the generic-secret policy.
    #[default]
    Generic,
    /// Password-family assignment or isolated password evidence.
    Password,
    /// Token/secret keyword-family evidence.
    Token,
    /// API/access-key and cryptographic-key evidence.
    ApiKey,
}

/// Detector-owned entry roles for the shared entropy engine.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum EntropyDetectionRole {
    /// Own anchor-free high-entropy candidates.
    KeywordFree,
    /// Own isolated bare candidates admitted by a detector shape policy.
    IsolatedBare,
    /// Own credential keywords not explicitly claimed by another detector.
    UnclaimedKeyword,
}

impl EntropyDetectionRole {
    /// Stable serialized spelling used by diagnostics and policy hashes.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::KeywordFree => "keyword-free",
            Self::IsolatedBare => "isolated-bare",
            Self::UnclaimedKeyword => "unclaimed-keyword",
        }
    }
}

impl EntropyFallbackClass {
    /// Stable serialized spelling used by explain output and policy hashes.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Generic => "generic",
            Self::Password => "password",
            Self::Token => "token",
            Self::ApiKey => "api-key",
        }
    }
}

/// Character class an isolated entropy shape admits. Replaces the former
/// per-shape enum variant so a new shape family is TOML data, not scanner code.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ShapeCharset {
    /// Lowercase letters and digits only.
    LowerAlnum,
    /// Hexadecimal digits only.
    Hex,
    /// Standard base64 alphabet (`A-Za-z0-9`, `+`, `/`, optional `=` padding).
    Base64Standard,
    /// URL-safe base64 alphabet (`A-Za-z0-9`, `-`, `_`).
    Base64Url,
}

fn default_shape_separator() -> char {
    '-'
}

/// Fixed-width separator grouping, e.g. a Bluesky app password's four
/// dash-separated groups of four. Absent means an ungrouped run.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ShapeGrouping {
    /// Number of separator-delimited groups.
    pub group_count: usize,
    /// Exact byte length of every group.
    pub group_length: usize,
    /// Character that separates the groups.
    #[serde(default = "default_shape_separator")]
    pub separator: char,
}

/// A declarative structural shape that may cross a detector's broad isolated
/// entropy floor. Every field is detector TOML data and the scanner keeps one
/// general matcher, so a new shape family (base64, hex block) is added by a
/// detector TOML rather than a scanner enum variant.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct EntropyShapeSpec {
    /// Character class the candidate body must consist of.
    pub charset: ShapeCharset,
    /// Minimum Shannon entropy in bits/byte.
    pub entropy_floor: f64,
    /// Minimum candidate length used by the isolated-shape revisit. This may be
    /// below the detector's broad keyword-free minimum.
    pub special_min_length: usize,
    /// Optional separator grouping. Absent means an ungrouped run.
    #[serde(default)]
    pub grouping: Option<ShapeGrouping>,
    /// Require both a lowercase and an uppercase letter.
    #[serde(default)]
    pub require_mixed_case: bool,
    /// Require at least one digit.
    #[serde(default)]
    pub require_digit: bool,
    /// Minimum count of symbol (non-alphanumeric) bytes.
    #[serde(default)]
    pub min_symbols: usize,
    /// Require at least one non-hex alphabetic byte, distinguishing an app
    /// password from a pure-hex digest of the same layout.
    #[serde(default)]
    pub require_non_hex_alpha: bool,
    /// When grouped, require every group to contain at least one letter and one
    /// digit (the app-password per-group rule).
    #[serde(default)]
    pub require_group_alpha_digit: bool,
}

/// One detector-local pure-hex key-material policy.
///
/// A candidate is eligible only when its captured assignment key matches one of
/// `keywords`, ends with one of `suffixes`, and is not in `excluded_keywords`
/// after normal assignment-key case/separator normalization. Its exact
/// character count must appear in `lengths`. The scanner still applies entropy,
/// placeholder, context, and reporting gates.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct CanonicalHexKeyMaterialSpec {
    /// Exact pure-hex character counts admitted by this policy.
    #[serde(default)]
    pub lengths: Vec<usize>,
    /// Assignment keys owned by a phase-2 generic policy. Each must also appear
    /// in the detector's top-level `keywords` list. Regex policies leave this
    /// empty because their matched pattern supplies the scope.
    #[serde(default)]
    pub keywords: Vec<String>,
    /// Normalized phase-2 assignment-key suffixes that may own this policy. This
    /// expresses vendor-prefixed names such as `stripe_secret_key` without a
    /// scanner-global suffix heuristic.
    #[serde(default)]
    pub suffixes: Vec<String>,
    /// Normalized phase-2 assignment keys excluded from suffix ownership, such
    /// as the ambiguous `license_key` shape.
    #[serde(default)]
    pub excluded_keywords: Vec<String>,
}

impl DetectorSpec {
    /// Whether this detector supplies policy to the generic entropy engine.
    pub fn owns_entropy_policy(&self) -> bool {
        self.kind == DetectorKind::Phase2Generic || self.entropy_policy_priority.is_some()
    }

    /// Return the stable, redaction-safe declaration used by detector
    /// introspection surfaces.
    ///
    /// The projection starts from `DetectorSpec`'s own serializer. Fields that
    /// describe identity and matching stay at the top level; every other
    /// declared field moves into `policy`. This means a newly added detector
    /// field is included automatically instead of requiring a second manual
    /// field list in each CLI surface. Inline fixture bytes are replaced with
    /// positive/negative coverage booleans.
    pub fn introspection(&self) -> DetectorIntrospection<'_> {
        DetectorIntrospection { detector: self }
    }

    /// Whether this detector admits transport-decoded pure-hex key material at
    /// the exact declared character count.
    pub fn allows_decoded_hex_key_material(&self, value: &str) -> bool {
        value.bytes().all(|byte| byte.is_ascii_hexdigit())
            && self.decoded_hex_key_material_lengths.contains(&value.len())
    }

    /// Whether this detector admits a transport wrapper whose decoded payload
    /// is pure hex at the exact declared character count.
    pub fn allows_decoded_hex_key_material_len(&self, decoded_len: Option<usize>) -> bool {
        decoded_len.is_some_and(|length| self.decoded_hex_key_material_lengths.contains(&length))
    }

    /// Whether this detector's canonical-hex policy admits an exact assignment
    /// key and pure-hex value pair.
    pub fn allows_canonical_hex_key_material(&self, keyword: &str, value: &str) -> bool {
        if !value.bytes().all(|byte| byte.is_ascii_hexdigit()) {
            return false;
        }
        self.canonical_hex_key_material.iter().any(|policy| {
            if !policy.lengths.contains(&value.len()) {
                return false;
            }
            if policy
                .excluded_keywords
                .iter()
                .any(|excluded| compact_assignment_keywords_equal(keyword, excluded))
            {
                return false;
            }
            policy
                .keywords
                .iter()
                .any(|owned_keyword| compact_assignment_keywords_equal(keyword, owned_keyword))
                || policy
                    .suffixes
                    .iter()
                    .any(|suffix| compact_assignment_keyword_ends_with(keyword, suffix))
        })
    }
}

/// Redaction-safe serialized view of one detector declaration.
pub struct DetectorIntrospection<'a> {
    detector: &'a DetectorSpec,
}

impl Serialize for DetectorIntrospection<'_> {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        let serialized = serde_json::to_value(self.detector).map_err(S::Error::custom)?;
        let serde_json::Value::Object(mut declared) = serialized else {
            return Err(S::Error::custom(
                "DetectorSpec serialization must produce a JSON object",
            ));
        };

        let tests = declared
            .remove("tests")
            .ok_or_else(|| S::Error::custom("DetectorSpec serialization omitted tests"))?
            .as_array()
            .cloned()
            .ok_or_else(|| S::Error::custom("DetectorSpec tests must serialize as an array"))?;
        let test_contracts = tests
            .into_iter()
            .map(|test| {
                let positive = test
                    .get("test_positive")
                    .is_some_and(|value| !value.is_null());
                let negative = test
                    .get("test_negative")
                    .is_some_and(|value| !value.is_null());
                serde_json::json!({
                    "positive": positive,
                    "negative": negative,
                })
            })
            .collect();

        let verification = declared
            .remove("verify")
            .ok_or_else(|| S::Error::custom("DetectorSpec serialization omitted verify"))?;
        let has_verification = !verification.is_null();

        let mut output = serde_json::Map::new();
        for field in [
            "id",
            "name",
            "service",
            "severity",
            "keywords",
            "simdsieve_prefixes",
            "patterns",
            "companions",
        ] {
            let Some(value) = declared.remove(field) else {
                return Err(S::Error::custom(format!(
                    "DetectorSpec serialization omitted required field {field:?}"
                )));
            };
            output.insert(field.to_string(), value);
        }
        output.insert(
            "verify".to_string(),
            serde_json::Value::Bool(has_verification),
        );
        output.insert("verification".to_string(), verification);
        output.insert(
            "test_contracts".to_string(),
            serde_json::Value::Array(test_contracts),
        );
        output.insert("policy".to_string(), serde_json::Value::Object(declared));

        serde_json::Value::Object(output).serialize(serializer)
    }
}

fn compact_assignment_keywords_equal(left: &str, right: &str) -> bool {
    compact_assignment_keyword_bytes(left).eq(compact_assignment_keyword_bytes(right))
}

fn compact_assignment_keyword_ends_with(value: &str, suffix: &str) -> bool {
    let value_len = compact_assignment_keyword_bytes(value).count();
    let suffix_len = compact_assignment_keyword_bytes(suffix).count();
    // A suffix policy describes a vendor-prefixed assignment (`stripe_key`),
    // not the bare suffix itself (`key`). Exact names belong in `keywords`,
    // which keeps the policy explicit and preserves the bare-key digest gate.
    suffix_len > 0
        && value_len > suffix_len
        && compact_assignment_keyword_bytes(value)
            .skip(value_len - suffix_len)
            .eq(compact_assignment_keyword_bytes(suffix))
}

fn compact_assignment_keyword_bytes(value: &str) -> impl Iterator<Item = u8> + '_ {
    value
        .bytes()
        .filter(|byte| !matches!(byte, b'_' | b'-' | b'.'))
        .map(|byte| byte.to_ascii_lowercase())
}

/// Per-detector credential SHAPE constraint (`[detector.credential_shape]`),
/// OWNED HERE per the architecture law (was a centralized
/// `rules/detector-credential-shapes.toml` `[[shape]]` list keyed by detector
/// id, a per-detector property in a second file). A candidate whose byte length
/// / prefix / post-prefix body length does not fit the declared shape is
/// suppressed by the scanner's shape gate (`CredentialShapeRule::allows`). Only a
/// couple of fixed-format vendor detectors declare it: `aws-access-key` is
/// exactly 20 bytes; `anthropic-api-key` is `sk-ant-api03-` + an 80..=120 body.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct CredentialShape {
    /// Exact total credential byte length, for a fixed-length format.
    #[serde(default)]
    pub exact_length: Option<usize>,
    /// Literal prefix. The body-length bounds below apply ONLY to a candidate
    /// that starts with this prefix (a differently-shaped credential is not
    /// owned by this rule and passes untouched).
    #[serde(default)]
    pub prefix: Option<String>,
    /// Minimum body byte length AFTER `prefix` (requires `prefix`).
    #[serde(default)]
    pub body_min_length: Option<usize>,
    /// Maximum body byte length AFTER `prefix` (requires `prefix`).
    #[serde(default)]
    pub body_max_length: Option<usize>,
}

impl CredentialShape {
    /// Validate the internal consistency of a declared shape (the single owner of
    /// these rules, was `credential_shapes::validate_shape_entries`). `detector_id`
    /// is only used to build a precise error message. Fails closed so a malformed
    /// per-detector shape is caught at load/build, never silently ignored.
    pub fn validate(&self, detector_id: &str) -> Result<(), String> {
        let has_constraint = self.exact_length.is_some()
            || self.prefix.is_some()
            || self.body_min_length.is_some()
            || self.body_max_length.is_some();
        if !has_constraint {
            return Err(format!(
                "credential shape for '{detector_id}' has no shape constraints"
            ));
        }
        if self.prefix.is_some()
            && self.exact_length.is_none()
            && self.body_min_length.is_none()
            && self.body_max_length.is_none()
        {
            return Err(format!(
                "credential shape for '{detector_id}' has a prefix but no length constraint"
            ));
        }
        if self.exact_length == Some(0) {
            return Err(format!(
                "credential shape for '{detector_id}' has exact_length=0"
            ));
        }
        if self.prefix.as_deref() == Some("") {
            return Err(format!(
                "credential shape for '{detector_id}' has an empty prefix"
            ));
        }
        if let (Some(minimum), Some(maximum)) = (self.body_min_length, self.body_max_length) {
            if minimum > maximum {
                return Err(format!(
                    "credential shape for '{detector_id}' has body_min_length greater than body_max_length"
                ));
            }
        }
        if (self.body_min_length.is_some() || self.body_max_length.is_some())
            && self.prefix.is_none()
        {
            return Err(format!(
                "credential shape for '{detector_id}' sets body length without a prefix"
            ));
        }
        if let (Some(exact_length), Some(prefix)) = (self.exact_length, self.prefix.as_deref()) {
            if let Some(minimum) = self.body_min_length {
                let minimum_total = prefix.len().checked_add(minimum).ok_or_else(|| {
                    format!("credential shape for '{detector_id}' overflows prefix plus body_min_length")
                })?;
                if exact_length < minimum_total {
                    return Err(format!(
                        "credential shape for '{detector_id}' has exact_length below prefix plus body_min_length"
                    ));
                }
            }
            if let Some(maximum) = self.body_max_length {
                let maximum_total = prefix.len().checked_add(maximum).ok_or_else(|| {
                    format!("credential shape for '{detector_id}' overflows prefix plus body_max_length")
                })?;
                if exact_length > maximum_total {
                    return Err(format!(
                        "credential shape for '{detector_id}' has exact_length above prefix plus body_max_length"
                    ));
                }
            }
        }
        Ok(())
    }
}

/// One inline detector self-test fixture (`[[detector.tests]]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct DetectorTestSpec {
    /// Text this detector MUST fire on.
    #[serde(default)]
    pub test_positive: Option<String>,
    /// Text this detector MUST NOT fire on.
    #[serde(default)]
    pub test_negative: Option<String>,
}

/// A regex pattern with optional capture group and description.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct PatternSpec {
    /// Regular expression string (Rust flavor). The owning detector TOML
    /// defines its exact separator and quantifier semantics; loading never
    /// rewrites the expression.
    pub regex: String,
    /// Optional context description.
    pub description: Option<String>,
    /// Optional capture group index containing the secret.
    pub group: Option<usize>,
    /// ASCII literals used only for candidate routing. Every full regex match
    /// must contain at least one declared literal; detector validation proves
    /// that OR-condition from the regex AST before the corpus can load.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub required_literals: Vec<String>,
    /// When true, a match against THIS pattern downgrades the
    /// finding to `Severity::ClientSafe` (regardless of the detector's
    /// nominal severity). Used by services that intentionally ship
    /// public-facing keys in client bundles:
    ///
    ///   - Sentry DSN (the `https://<key>@` URL is meant for the browser)
    ///   - Stripe `pk_live_` / `pk_test_` (publishable, sk_ is secret)
    ///   - Mapbox `pk.` (public, `sk.` is secret)
    ///   - Firebase Web API key, Google Maps browser key
    ///   - PostHog / Mixpanel / Algolia search / Datadog browser RUM
    ///
    /// Per-pattern (not per-detector) so detectors that fire on both
    /// the public *and* the secret prefix can tag only the public one.
    ///
    /// Case sensitivity: keyhog compiles every regex `case_insensitive(true)`,
    /// so to make a single pattern case-SENSITIVE (AWS `AKIA` is uppercase,
    /// GCP/Snowflake ids are lowercase) prefix its regex with the inline flag
    /// `(?-i)` in the TOML - no schema field needed.
    #[serde(default)]
    pub client_safe: bool,
    /// Keep generic shape and entropy gates active for matches from this
    /// pattern. Declare this beside the regex so policy cannot drift when a
    /// detector's patterns are reordered. Detector-level `weak_anchor = true`
    /// applies the same policy to every pattern.
    #[serde(default)]
    pub weak_anchor: bool,
    /// Treat matches from this exact regex as syntactically proven password
    /// slots. Unlike the detector-level flag, this does not exempt generic
    /// keyword-bridge candidates or sibling patterns from Tier-B shape gates.
    #[serde(default)]
    pub structural_password_slot: bool,
}

impl PatternSpec {
    /// Validate that the declared routing literals are a necessary OR-condition
    /// of every regex match. The proof is conservative: declarations that span
    /// optional or structurally ambiguous AST nodes are rejected.
    pub fn validate_required_literals(&self) -> Result<(), String> {
        use regex_syntax::ast::{parse::Parser, Ast, RepetitionKind, RepetitionRange};

        if self.required_literals.is_empty() {
            return Ok(());
        }
        if self
            .required_literals
            .iter()
            .any(|literal| literal.is_empty() || !literal.is_ascii())
        {
            return Err("must contain only non-empty ASCII strings".into());
        }
        let mut literals = self
            .required_literals
            .iter()
            .map(|literal| literal.to_ascii_lowercase())
            .collect::<Vec<_>>();
        literals.sort_unstable();
        if literals.windows(2).any(|pair| pair[0] == pair[1]) {
            return Err("contains a duplicate ASCII-insensitive literal".into());
        }

        fn repetition_min(kind: &RepetitionKind) -> u32 {
            match kind {
                RepetitionKind::ZeroOrOne | RepetitionKind::ZeroOrMore => 0,
                RepetitionKind::OneOrMore => 1,
                RepetitionKind::Range(RepetitionRange::Exactly(min))
                | RepetitionKind::Range(RepetitionRange::AtLeast(min))
                | RepetitionKind::Range(RepetitionRange::Bounded(min, _)) => *min,
            }
        }

        fn guarantees(ast: &Ast, literals: &[String]) -> bool {
            fn run_contains(run: &str, literals: &[String]) -> bool {
                let folded = run.to_ascii_lowercase();
                literals.iter().any(|literal| folded.contains(literal))
            }

            match ast {
                Ast::Literal(literal) => run_contains(&literal.c.to_string(), literals),
                Ast::Group(group) => guarantees(&group.ast, literals),
                Ast::Alternation(alternation) => {
                    !alternation.asts.is_empty()
                        && alternation
                            .asts
                            .iter()
                            .all(|branch| guarantees(branch, literals))
                }
                Ast::Repetition(repetition) => {
                    repetition_min(&repetition.op.kind) > 0 && guarantees(&repetition.ast, literals)
                }
                Ast::Concat(concat) => {
                    let mut run = String::new();
                    for node in &concat.asts {
                        if let Ast::Literal(literal) = node {
                            run.push(literal.c);
                            continue;
                        }
                        if run_contains(&run, literals) || guarantees(node, literals) {
                            return true;
                        }
                        run.clear();
                    }
                    run_contains(&run, literals)
                }
                Ast::Empty(_)
                | Ast::Dot(_)
                | Ast::Assertion(_)
                | Ast::ClassUnicode(_)
                | Ast::ClassPerl(_)
                | Ast::ClassBracketed(_)
                | Ast::Flags(_) => false,
            }
        }

        let ast = Parser::new()
            .parse(&self.regex)
            .map_err(|error| format!("cannot prove literals against invalid regex: {error}"))?;
        if guarantees(&ast, &literals) {
            Ok(())
        } else {
            Err("is not a proven necessary OR-condition of every regex match".into())
        }
    }
}

/// Secondary pattern used to confirm a primary match or provide extra context.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CompanionSpec {
    /// Field name used in verification templates (e.g. \`{{companion.secret_key}}\`).
    pub name: String,
    /// Regex to find the companion value nearby. The owning detector TOML
    /// defines its exact semantics; loading never rewrites the expression.
    pub regex: String,
    /// Maximum line distance from the primary match.
    pub within_lines: usize,
    /// Whether this companion must be found to report the finding.
    #[serde(default)]
    pub required: bool,
}

/// Live verification configuration for a detector.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct VerifySpec {
    /// Target service identifier (defaults to detector's service if omitted).
    #[serde(default)]
    pub service: String,
    /// HTTP method (default: GET).
    pub method: Option<HttpMethod>,
    /// Endpoint URL with optional \`{{match}}\` or \`{{companion.<name>}}\` placeholders.
    pub url: Option<String>,
    /// Authentication scheme.
    pub auth: Option<AuthSpec>,
    /// Custom HTTP headers.
    #[serde(default)]
    pub headers: Vec<HeaderSpec>,
    /// Optional request body template.
    pub body: Option<String>,
    /// Criteria for a successful verification.
    pub success: Option<SuccessSpec>,
    /// Metadata to extract from the response.
    #[serde(default)]
    pub metadata: Vec<MetadataSpec>,
    /// Optional request timeout override.
    pub timeout_ms: Option<u64>,
    /// Multi-step verification flow.
    #[serde(default)]
    pub steps: Vec<StepSpec>,
    /// Domain allowlist for the verify URL after interpolation. If non-empty,
    /// the resolved host of the (interpolated) URL - and of every step's URL -
    /// MUST equal one of these entries (or be a subdomain of one). When empty,
    /// the verifier falls back to a hardcoded service allowlist if the
    /// `service` field maps to a known provider; otherwise the verifier
    /// REFUSES to send the request. This blocks malicious detector TOMLs
    /// that set `url = "{{match}}"` (or interpolate an attacker-controlled
    /// companion) from exfiltrating credentials. See kimi-wave1 audit
    /// finding 4.1 + wave3 §1.
    #[serde(default)]
    pub allowed_domains: Vec<String>,
    /// Optional out-of-band verification probe. When set, the verifier mints a
    /// per-finding correlation URL via the configured interactsh server,
    /// substitutes `{{interactsh}}` (and `{{interactsh.host}}` /
    /// `{{interactsh.url}}`) into the request template, and waits for the
    /// service to call back. OOB verification proves a leaked credential is
    /// **exfil-capable**, not just live: a webhook URL that returns 200 OK to
    /// every probe still has to actually fetch our collector to confirm it
    /// will deliver attacker-controlled traffic.
    ///
    /// Gated behind the runtime `--verify-oob` flag - never default. When a
    /// detector sets `oob`, verification requires an active OOB session and
    /// fails closed if the session is unavailable, rather than sending a
    /// malformed HTTP-only probe with empty interactsh substitutions.
    pub oob: Option<OobSpec>,
}

/// Out-of-band callback verification configuration.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OobSpec {
    /// Callback protocol the verifier waits for. The service may also touch
    /// other protocols on the same correlation id; only the listed ones count
    /// toward `Verified`.
    pub protocol: OobProtocol,
    /// How long to wait for the callback after the HTTP request returns.
    /// Defaults to 30 seconds when omitted; capped at the engine's
    /// `oob_timeout_max` to bound scan time.
    #[serde(default)]
    pub timeout_secs: Option<u64>,
    /// Verification policy (TOML wire values shown; serde is `snake_case`):
    /// - `oob_and_http` (default): both HTTP success criteria *and* OOB
    ///   callback must hold. This is the strict mode for webhook-style
    ///   detectors where 200 OK is necessary but not sufficient.
    /// - `oob_only`: ignore HTTP success, trust the OOB callback. For
    ///   detectors where the API has no useful HTTP response shape but
    ///   provably triggers an outbound request (e.g., one-way push tokens).
    /// - `oob_optional`: HTTP success alone verifies; OOB just enriches
    ///   metadata with `oob_observed=true|false` for the report.
    #[serde(default)]
    pub policy: OobPolicy,
}

/// Out-of-band callback protocol expected from a successful exfil.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum OobProtocol {
    /// Any DNS resolution against `{{interactsh}}.host`. Cheapest signal -
    /// many services resolve a webhook URL even before fetching it.
    Dns,
    /// HTTP or HTTPS request to the interactsh URL. The strongest signal;
    /// proves the service made an outbound HTTP request with the credential.
    Http,
    /// SMTP delivery attempt to `<random>@{{interactsh.host}}`. For mail
    /// detectors (Mailgun, SendGrid, …) where exfil = sending mail.
    Smtp,
    /// Any of the above. Use sparingly - a chatty CDN doing DNS prefetch
    /// can cause false positives.
    Any,
}

/// How OOB observation combines with HTTP success criteria.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum OobPolicy {
    #[default]
    OobAndHttp,
    OobOnly,
    OobOptional,
}

/// A single step in a multi-step verification flow.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StepSpec {
    pub name: String,
    pub method: HttpMethod,
    pub url: String,
    pub auth: AuthSpec,
    #[serde(default)]
    pub headers: Vec<HeaderSpec>,
    pub body: Option<String>,
    pub success: SuccessSpec,
    #[serde(default)]
    pub extract: Vec<MetadataSpec>,
}

/// Custom HTTP header specification.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HeaderSpec {
    pub name: String,
    pub value: String,
}

/// Authentication scheme for verification requests.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum AuthSpec {
    None {},
    Bearer {
        field: String,
    },
    Basic {
        username: String,
        password: String,
    },
    Header {
        name: String,
        template: String,
    },
    Query {
        param: String,
        field: String,
    },
    #[serde(rename = "aws_v4")]
    AwsV4 {
        access_key: String,
        secret_key: String,
        region: String,
        service: String,
        session_token: Option<String>,
    },
    Script {
        engine: ScriptEngine,
        code: String,
    },
}

/// Script interpreter names accepted by the detector TOML schema.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScriptEngine {
    Python3,
    Python,
    Node,
    Other(String),
}

impl ScriptEngine {
    pub const ALLOWED_FOR_VERIFY: &'static [&'static str] = &["python3", "python", "node"];

    pub fn as_str(&self) -> &str {
        match self {
            Self::Python3 => "python3",
            Self::Python => "python",
            Self::Node => "node",
            Self::Other(engine) => engine,
        }
    }

    pub fn is_allowed_for_verify(&self) -> bool {
        matches!(self, Self::Python3 | Self::Python | Self::Node)
    }
}

impl From<String> for ScriptEngine {
    fn from(engine: String) -> Self {
        match engine.as_str() {
            "python3" => Self::Python3,
            "python" => Self::Python,
            "node" => Self::Node,
            _ => Self::Other(engine),
        }
    }
}

impl From<&str> for ScriptEngine {
    fn from(engine: &str) -> Self {
        Self::from(engine.to_owned())
    }
}

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

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

impl<'de> Deserialize<'de> for ScriptEngine {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        Ok(String::deserialize(deserializer)?.into())
    }
}

/// How a verifier response establishes a successful credential check.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SuccessPolicy {
    /// Stable response-body evidence must match.
    BodyPositive,
    /// The accepted status is necessary, then the generic provider-error body
    /// backstop must still reject populated error signals.
    StatusWithErrorBackstop,
    /// The provider protocol makes the accepted status authoritative even when
    /// the response body is empty or unstable.
    StatusAuthoritative,
}

/// Criteria for a successful verification response.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct SuccessSpec {
    #[serde(default)]
    /// Required HTTP status code.
    pub status: Option<u16>,
    #[serde(default)]
    /// Reject if this status code is returned.
    pub status_not: Option<u16>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Explicit response-success policy. Shipped detector contracts must
    /// classify this; `None` exists only for backwards-compatible decoding and
    /// is rejected by detector quality validation.
    pub policy: Option<SuccessPolicy>,
    #[serde(default)]
    /// Response body must contain this substring.
    pub body_contains: Option<String>,
    #[serde(default)]
    /// Response body must NOT contain this substring.
    pub body_not_contains: Option<String>,
    #[serde(default)]
    /// `$`-rooted response selector to check in the JSON response body.
    pub json_path: Option<String>,
    #[serde(default)]
    /// Expected value at \`json_path\`.
    pub equals: Option<String>,
}

/// Migrate unambiguous schema-v1 status-only success contracts to the
/// conservative explicit policy.
///
/// Returns the number of contracts migrated so the loader can surface legacy
/// normalization. Body-constrained, no-status, and already-classified contracts
/// remain untouched and will pass or fail normal validation without guessing.
pub(crate) fn migrate_legacy_success_policies(detector: &mut DetectorSpec) -> usize {
    let Some(verify) = detector.verify.as_mut() else {
        return 0;
    };

    let mut migrated = verify
        .success
        .as_mut()
        .is_some_and(migrate_legacy_success_policy) as usize;
    for step in &mut verify.steps {
        migrated += migrate_legacy_success_policy(&mut step.success) as usize;
    }
    migrated
}

fn migrate_legacy_success_policy(success: &mut SuccessSpec) -> bool {
    let is_unambiguous_status_only = success.policy.is_none()
        && success.status.is_some()
        && success.body_contains.is_none()
        && success.body_not_contains.is_none()
        && success.json_path.is_none()
        && success.equals.is_none();
    if !is_unambiguous_status_only {
        return false;
    }

    success.policy = Some(SuccessPolicy::StatusWithErrorBackstop);
    true
}

/// Severity level for a finding.
///
/// `ClientSafe` is the bug-bounty tier for keys that are public by
/// design and shipped in client bundles: Sentry DSNs, Stripe `pk_*`
/// publishable keys, Mapbox `pk.` public tokens, PostHog project keys,
/// Firebase Web API keys, Google Maps browser keys, Algolia search
/// keys, Datadog browser RUM tokens, Mixpanel project tokens. The
/// detector still fires (a token grep is a token grep) but the
/// finding is rendered below `Low` and gated by `--hide-client-safe`
/// so a hunter running `keyhog scan --hide-client-safe target/` only
/// sees credentials that an attacker could actually exfiltrate
/// server-side.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Default)]
#[serde(rename_all = "kebab-case")]
pub enum Severity {
    #[default]
    Info,
    ClientSafe,
    Low,
    Medium,
    High,
    Critical,
}

/// Canonical `kebab-case` severity wire forms in `ORDERED` order, the set an
/// unknown-token deserialize error advertises. DERIVED (const-evaluated) from the
/// single [`Severity::ORDERED`] + [`Severity::as_str`] table so it can never drift
/// from what the enum actually renders and accepts: a variant added to `ORDERED`
/// appears here, and in the deserialize accept-list and the unknown-variant
/// diagnostic, automatically, with no second hand-maintained string list. Lists
/// only the canonical spellings and deliberately omits the private `client_safe`
/// back-compat alias (still *accepted* on input by the visitor below, never
/// advertised).
const SEVERITY_CANONICAL_WIRE_FORMS: [&str; Severity::ORDERED.len()] = {
    let mut out = [""; Severity::ORDERED.len()];
    let mut i = 0;
    while i < Severity::ORDERED.len() {
        out[i] = Severity::ORDERED[i].as_str();
        i += 1;
    }
    out
};

// Hand-written `Deserialize` (Serialize stays derived; `rename_all` makes it
// re-emit the canonical kebab form). Two reasons the derive is not enough:
//   * a non-string input (number/bool/null) must fail with an `invalid type`
//     error, the categorically-correct diagnostic, not the derive's
//     variant-identifier path; and
//   * an unknown token must advertise ONLY the canonical kebab forms while the
//     visitor still accepts the `client_safe` snake alias on input.
// Match is exact: case-sensitive and non-trimming (` critical `, `Critical`,
// `CLIENT-SAFE` all fail closed). No binary/non-self-describing serde path
// exists for `Severity` (every load is `serde_json`/`toml`, both self-describing
// with string values), so `deserialize_str` is safe here.
impl<'de> serde::Deserialize<'de> for Severity {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        struct SeverityVisitor;

        impl serde::de::Visitor<'_> for SeverityVisitor {
            type Value = Severity;

            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str(
                    "a severity string (one of info, client-safe, low, medium, high, critical)",
                )
            }

            fn visit_str<E>(self, value: &str) -> Result<Severity, E>
            where
                E: serde::de::Error,
            {
                // Private back-compat alias, deliberately NOT a canonical wire
                // form (kept out of `as_str`/the advertised set).
                if value == "client_safe" {
                    return Ok(Severity::ClientSafe);
                }
                // Canonical match is EXACT (case-sensitive, non-trimming): compare
                // the input against each variant's single-source-of-truth
                // `as_str`, so `Critical`/` critical `/`CLIENT-SAFE`/`` all fall
                // through to the fail-closed unknown-variant path below.
                Severity::ORDERED
                    .iter()
                    .find(|variant| variant.as_str() == value)
                    .copied()
                    .ok_or_else(|| E::unknown_variant(value, &SEVERITY_CANONICAL_WIRE_FORMS))
            }
        }

        deserializer.deserialize_str(SeverityVisitor)
    }
}

impl Severity {
    pub(crate) const FILTER_EXPECTED_LABELS: &'static str =
        "info|client-safe|low|medium|high|critical";
    pub(crate) const ORDERED: [Severity; 6] = [
        Severity::Info,
        Severity::ClientSafe,
        Severity::Low,
        Severity::Medium,
        Severity::High,
        Severity::Critical,
    ];

    /// Step the severity down one tier (Critical → High, High → Medium, …).
    /// `Info` stays at `Info` (no lower bucket).
    ///
    /// Used by diff-aware scoring: a credential that only appears in non-HEAD
    /// git history is still a leak (commit history is public if the repo is)
    /// but is meaningfully less urgent than a credential live in HEAD that an
    /// attacker can grep right now. One tier of downgrade communicates that
    /// without hiding the finding entirely.
    pub fn downgrade_one(self) -> Self {
        match self {
            Severity::Critical => Severity::High,
            Severity::High => Severity::Medium,
            Severity::Medium => Severity::Low,
            Severity::Low => Severity::ClientSafe,
            Severity::ClientSafe => Severity::Info,
            Severity::Info => Severity::Info,
        }
    }

    /// Canonical lowercase string for this severity, matching the serde
    /// `kebab-case` wire form (`client-safe`, not `clientsafe`). This is the
    /// single source of truth for rendering a severity as text; reporters and
    /// any other surface should go through `Display`/`as_str` rather than
    /// reaching for `format!("{:?}")`, which diverges for `ClientSafe`.
    ///
    /// Public so downstream crates (the CLI completion/severity summary,
    /// stream previews) render severity text from this one table instead of
    /// keeping their own `match` copies that can drift.
    pub const fn as_str(&self) -> &'static str {
        // THE single source of truth for every severity wire form. `const` so the
        // canonical-wire-form set, the deserialize accept-list, and the filter
        // parser all DERIVE from this one table at compile time instead of
        // re-listing the six (variant, string) pairs and risking drift.
        match self {
            Severity::Info => "info",
            Severity::ClientSafe => "client-safe",
            Severity::Low => "low",
            Severity::Medium => "medium",
            Severity::High => "high",
            Severity::Critical => "critical",
        }
    }

    pub(crate) fn from_filter_label(label: &str) -> Option<Self> {
        // Filter labels are lenient (trim + lowercase), unlike the exact
        // deserializer path above, but both resolve against the SAME single
        // `as_str` table so a new/renamed wire form is honoured everywhere at
        // once. `client_safe` snake alias is accepted here too.
        let normalized = label.trim().to_ascii_lowercase();
        if normalized == "client_safe" {
            return Some(Severity::ClientSafe);
        }
        Severity::ORDERED
            .iter()
            .find(|variant| variant.as_str() == normalized)
            .copied()
    }

    pub(crate) fn rank(self) -> usize {
        match Self::ORDERED
            .iter()
            .position(|candidate| *candidate == self)
        {
            Some(rank) => rank,
            None => Self::ORDERED.len() - 1, // LAW10: fail-closed/security: impossible enum/table drift clamps to highest severity so severity_lte cannot over-suppress.
        }
    }

    pub(crate) fn label_for_rank(rank: usize) -> &'static str {
        match Self::ORDERED.get(rank) {
            Some(severity) => severity.as_str(),
            None => Severity::Critical.as_str(), // LAW10: fail-closed/security: invalid rank maps to highest severity label so severity_lte cannot over-suppress.
        }
    }
}

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

/// HTTP method for verification requests.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum HttpMethod {
    #[serde(rename = "GET")]
    Get,
    #[serde(rename = "POST")]
    Post,
    #[serde(rename = "PUT")]
    Put,
    #[serde(rename = "DELETE")]
    Delete,
    #[serde(rename = "PATCH")]
    Patch,
    #[serde(rename = "HEAD")]
    Head,
}

/// Canonical file name for the directory-scoped detector corpus manifest.
pub const DETECTOR_CORPUS_MANIFEST_FILE: &str = "corpus.toml";

/// Oldest legacy detector schema this binary can migrate deterministically.
pub const DETECTOR_CORPUS_MIN_SCHEMA_VERSION: u32 = 1;

/// Detector schema authored and enforced by this binary.
pub const DETECTOR_CORPUS_SCHEMA_VERSION: u32 = 2;

/// Highest newer detector schema this binary may inspect additively.
///
/// A corpus beyond this one-version compatibility window is rejected before
/// any detector is loaded.
pub const DETECTOR_CORPUS_MAX_FORWARD_SCHEMA_VERSION: u32 = DETECTOR_CORPUS_SCHEMA_VERSION + 1;

/// Directory-scoped compatibility contract for detector TOML files.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorCorpusManifest {
    /// Schema version shared by every detector file in the directory.
    pub schema_version: u32,
}

/// Wrapping struct for a detector TOML file.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DetectorFile {
    pub detector: DetectorSpec,
}