khive_runtime/

secret_gate.rs

//! Write-time secret detection gate.
//!
//! Scans caller-supplied content strings before any storage write. A match
//! causes a hard `RuntimeError::SecretDetected` that names the detector and
//! carries a masked excerpt internally. Its display names the rule and trigger
//! without echoing any candidate text.
//!
//! Scope: **credentials only** — API keys, tokens, private keys, passwords,
//! and connection strings with embedded credentials. General PII (emails,
//! phone numbers, company names) is intentionally NOT blocked.
//!
//! Detection is layered, cheap-first:
//! 1. **Known-prefix / known-shape patterns** — AWS AKIA/ASIA, GitHub tokens,
//!    OpenAI `sk-proj-`, Anthropic `sk-ant-`, Stripe live keys, Fly.io tokens,
//!    Vercel secrets, Slack `xox*`, JWT triples, PEM private-key headers, Age
//!    secret keys, URL userinfo (`scheme://user:pass@`).
//! 2. **High-entropy token heuristic** — base64/hex/base64url runs ≥ 24 chars
//!    near a trigger word (key, secret, password, credential, bearer, auth,
//!    apikey, api_key, access_key, private_key). A standalone `token` still
//!    triggers opaque entropy detection, but does not by itself label a UUID
//!    as a credential; compound identifiers such as `tokenizer_*` and
//!    `token_count` remain excluded.
//!
//! Credential-shaped labels and assignments dominate the allowlist below.
//! Public VCS revisions and plausible file paths remain exempt in ordinary
//! technical prose, while path segments are still scanned independently.
//!
//! Full exemption rules (hex/UUID/SRI-hash passes, non-ASCII token
//! delimiting, structured-identifier decomposition, trigger word-boundary
//! matching, the underscore-boundary asymmetry between bare trigger words and
//! the word `token`, and the adversarial-corpus rationale for why some
//! false positives are accepted) are documented in full in
//! `docs/api/secret_gate.md#module-level-detection-algorithm` — read that before
//! changing any detection or exemption logic in this file.
//!
//! The caller-visible block message (`SecretMatch`'s `Display` impl) also
//! carries actionable guidance (`block_guidance`) to split or reword the
//! flagged token.
//!
//! A production-corpus replay harness (`corpus_replay`, `#[ignore]`d, run via
//! `KHIVE_REPLAY_DB=<path> cargo test ... -- --ignored --nocapture`) measures
//! the detector's block rate against real note/entity content; see the
//! harness's own output for current numbers rather than a point-in-time count
//! here, which would drift as the corpus changes. A checked-in, sanitized
//! snapshot of that replay (per-detector block counts and sha256 digests of
//! blocked content, never the content itself) lives at
//! `tests/data/secret_gate_corpus_manifest.md`, generated by
//! `corpus_replay::generate_corpus_manifest`.
//! A replay that is identical before and after a change certifies preservation
//! on the corpus population only, never on the shape class the change opens;
//! that class needs its own before/after arms.

use crate::error::{RuntimeError, RuntimeResult};

mod submitted_atom_digest;

pub use submitted_atom_digest::masked_submitted_atom_digest_v1;

// ─── Public API ──────────────────────────────────────────────────────────────

/// Returned when a write would store credential-looking content.
///
/// Carries the detector name and a masked excerpt (`first6...Nchars`).  The
/// full candidate is never stored in the error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SecretMatch {
    /// Human-readable name of the detector that fired.
    pub detector: &'static str,
    /// Canonical trigger from the matched context; known-prefix rules need none.
    pub trigger: Option<&'static str>,
    /// `first6...N` — the first 6 chars of the match followed by the total length.
    pub masked: String,
    /// Which record and field the match came from. `None` only where the
    /// caller scanned exactly one string and nothing else, so there is one
    /// candidate. A single-record verb that scans several fields still needs
    /// this: the writer sees one refusal and cannot tell whether it was the
    /// name, the content, a tag or a property that matched.
    pub location: Option<String>,
}

impl std::fmt::Display for SecretMatch {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "content matches secret pattern {}", self.detector)?;
        if let Some(trigger) = self.trigger {
            write!(f, " near '{trigger}'")?;
        }
        if let Some(location) = &self.location {
            write!(f, " in {location}")?;
        }
        write!(f, ". {}", block_guidance(self.detector))
    }
}

/// Actionable, caller-visible guidance for a hard block, keyed by detector
/// name. If the content genuinely is a credential, remove it. If it
/// is not — the common case for the detectors below, which key off SHAPE
/// near a trigger word rather than a known credential prefix — the fix is to
/// break up the flagged token so it no longer reads as one contiguous
/// high-entropy value: separate it from words like key/secret/auth/token with
/// a sentence or paragraph boundary, or use an explicit repository revision
/// reference for a source hash.
fn block_guidance(detector: &'static str) -> &'static str {
    match detector {
        "url-userinfo" => {
            "Placeholders in URL credential positions still match this pattern. \
             Replace the whole URL with an environment-variable name or config key, \
             or remove the entire user/password segment before writing."
        }
        "high-entropy-token"
        | "uuid-near-trigger"
        | "content-hash-near-trigger"
        | "hex-credential-token" => {
            "If this is a real credential, remove it before writing. If it is not \
             (e.g. a file path, UUID, or hash that happens to sit near a word like \
             key/secret/auth/token), put the candidate in a separate sentence or \
             paragraph from those words, or express a source hash as an explicit \
             commit/revision reference."
        }
        _ => {
            "If this is a real credential, remove it before writing; store secrets \
              in an env var or secrets manager instead."
        }
    }
}

/// Hard-block content from being written.
///
/// Returns `Err(RuntimeError::SecretDetected)` on the first match found, or
/// `Ok(())` if no secret pattern fires.
pub fn check(content: &str) -> RuntimeResult<()> {
    if let Some(m) = scan(content) {
        return Err(RuntimeError::SecretDetected(m));
    }
    Ok(())
}

/// Recursively scan a JSON value for credential-shaped strings.
///
/// Walks every string leaf (object values, array elements, nested objects).
/// Returns `Err(RuntimeError::SecretDetected)` on the first match found.
/// `None` / null / numeric / boolean JSON values are skipped.
pub fn check_json(value: &serde_json::Value) -> RuntimeResult<()> {
    scan_json_value(value)
}

/// Scan a string-tagged slice (entity/note tags).
///
/// Each tag string is scanned individually.
pub fn check_tags(tags: &[String]) -> RuntimeResult<()> {
    for tag in tags {
        check(tag)?;
    }
    Ok(())
}

/// Name the scope and field a refusal came from.
///
/// A batch verb scans each record and returns on the first refusal, so the
/// caller gets ONE error for N records. Without this the error names only the
/// matched text, which by construction is text the caller cannot find: it sits
/// in whichever sibling record refused, and every other record in the call is
/// rejected with it (khive #2605). Pass through anything that is not a gate
/// refusal unchanged — this adds identity, it does not reclassify.
///
/// `record` names the record the field belongs to, as the caller submitted it:
/// `entity`, `note`, `task`, `proposal`, `message`, indexed when it came from a
/// batch (`note[2]`). It answers where in the submitted payload the writer
/// should look, which is the question a refused writer actually asks.
pub fn locate<T>(result: RuntimeResult<T>, record: &str, field: &str) -> RuntimeResult<T> {
    result.map_err(|error| match error {
        RuntimeError::SecretDetected(matched) => RuntimeError::SecretDetected(SecretMatch {
            location: Some(format!("{record}.{field}")),
            ..matched
        }),
        other => other,
    })
}

/// `check` that names where it looked. `record` is the record noun the caller
/// submitted, indexed inside a batch; `field` is the field of it that was scanned.
pub fn check_at(content: &str, record: &str, field: &str) -> RuntimeResult<()> {
    locate(check(content), record, field)
}

/// `check_json` that names where it looked. The location is the field holding
/// the JSON, not the path of the string leaf that matched inside it.
pub fn check_json_at(value: &serde_json::Value, record: &str, field: &str) -> RuntimeResult<()> {
    locate(check_json(value), record, field)
}

/// `check_tags` that names where it looked.
pub fn check_tags_at(tags: &[String], record: &str, field: &str) -> RuntimeResult<()> {
    locate(check_tags(tags), record, field)
}

// ─── Reserved property key (ADR-115 Amendment 1) ────────────────────────────

/// Top-level JSON property key reserved for runtime-owned exemption state.
///
/// No caller may create, replace, merge, or remove this key through any
/// properties-bearing write path — ADR-115 Amendment 1 §3. Reservation binds
/// unconditionally: the runtime does not yet stamp any record with this key
/// (the finalizer that would do so is a separate, later increment), so no
/// caller-supplied occurrence of it can ever be a legitimate echo of
/// persisted state. Only the exact top-level key is reserved; the same
/// spelling nested inside an object *value* is ordinary content and remains
/// subject to [`check_json`], never a posture mutation.
pub const RESERVED_SECRET_GATE_KEY: &str = "khive:secret_gate";

/// Reject a caller-supplied top-level `khive:secret_gate` property key.
///
/// Call this before any diff, merge, or storage preparation touches
/// caller-supplied `properties` on any properties-bearing write path —
/// create, patch update, or full replace. Returns `Ok(())` when `properties`
/// is absent, is not a JSON object, or does not name the reserved key at the
/// top level.
///
/// This is the one shared validator for the reservation rule (ADR-115
/// Amendment 1 §3); every properties-bearing write path across every crate
/// must call this instead of re-implementing the check.
pub fn reject_reserved_secret_gate_property(
    properties: Option<&serde_json::Value>,
) -> RuntimeResult<()> {
    if let Some(serde_json::Value::Object(map)) = properties {
        if map.contains_key(RESERVED_SECRET_GATE_KEY) {
            return Err(RuntimeError::InvalidInput(format!(
                "property key `{RESERVED_SECRET_GATE_KEY}` is runtime-owned and cannot be \
                 created, replaced, merged, or removed by callers"
            )));
        }
    }
    Ok(())
}

fn scan_json_value(value: &serde_json::Value) -> RuntimeResult<()> {
    match value {
        serde_json::Value::String(s) => check(s),
        serde_json::Value::Array(arr) => {
            for v in arr {
                scan_json_value(v)?;
            }
            Ok(())
        }
        serde_json::Value::Object(map) => {
            for (k, v) in map {
                // Scan both the key (a credential can appear as a JSON key name)
                // and the value recursively.
                check(k)?;
                scan_json_value(v)?;
            }
            Ok(())
        }
        _ => Ok(()),
    }
}

// ─── Scanner ─────────────────────────────────────────────────────────────────

/// Marker substituted for a detected secret span by [`mask_secrets`].
const REDACTION_MARKER: &str = "***MASKED***";

/// Maximum cumulative bytes revisited by the per-pass detector sweeps while masking
/// one input. Entropy tokens are materialized once, but resuming inside a token
/// rebuilds its member candidates and revisits their context, so that token's
/// full prefix is also charged. This permits two full-size passes over the 1 MiB
/// ASCII log-input case; the first pass is always allowed for larger or multibyte
/// callers. Once exhausted, the remainder is redacted wholesale.
const MAX_MASK_SCAN_WORK_BYTES: usize = MAX_LOG_TEXT_MASK_INPUT_CHARS * 2;

#[cfg(test)]
thread_local! {
    static ENTROPY_TOKENIZATION_COUNT: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

/// Return the LEFTMOST secret in `text` as `(matched_slice, detector)`.
///
/// The matched slice borrows from `text`, so the caller can recover its byte
/// span via pointer arithmetic — this is what lets [`mask_secrets`] redact in
/// place while [`scan`] only needs the masked excerpt.
///
/// "Leftmost" (smallest start offset), NOT first-by-detector-priority, is the
/// load-bearing contract: [`mask_secrets`] copies the text *before* each match
/// verbatim, so a non-leftmost match would leak an earlier secret detected by a
/// lower-priority detector (e.g. an `sk-ant-` key sitting to the left of a
/// `ghp_` token). Both detector layers are folded through [`keep_leftmost`].
#[cfg(test)]
fn scan_match(text: &str) -> Option<(&str, &'static str)> {
    let context = EntropyScanContext::new(text);
    scan_from(text, 0, &context)
}

/// Like [`scan_match`], but only returns secrets whose span starts at or after
/// `from`, while still evaluating Layer-2 trigger context against the FULL
/// `text`. [`mask_secrets`] calls this with an advancing `from` so that an
/// entropy token is detected even when its only trigger word sits to the left of
/// an already-redacted earlier secret. Layer-1 known patterns are context-free,
/// so scanning the `&text[from..]` suffix is equivalent; offsets recovered via
/// pointer arithmetic against the original `text` base stay absolute. The
/// pre-tokenized entropy view is shared by all passes.
fn scan_from<'a>(
    text: &'a str,
    from: usize,
    context: &EntropyScanContext<'a>,
) -> Option<(&'a str, &'static str)> {
    scan_from_with_trigger(text, from, context).map(|(slice, detector, _)| (slice, detector))
}

fn scan_from_with_trigger<'a>(
    text: &'a str,
    from: usize,
    context: &EntropyScanContext<'a>,
) -> Option<(&'a str, &'static str, Option<&'static str>)> {
    let mut best =
        check_known_patterns(&text[from..]).map(|(slice, detector)| (slice, detector, None));
    if let Some(candidate) = check_entropy_heuristic(text, from, context) {
        if best
            .as_ref()
            .is_none_or(|current| candidate.0.as_ptr() < current.0.as_ptr())
        {
            best = Some(candidate);
        }
    }
    best
}

/// Replace `best` with `cand` when `cand` starts earlier in the original text
/// (`base` is the start address of that text). On a tie the incumbent wins, so
/// callers offer more-specific detectors first. This is what makes
/// [`check_known_patterns`] and [`scan_match`] return the leftmost secret span
/// rather than the first detector that happens to match anywhere.
fn keep_leftmost<'a>(
    best: &mut Option<(&'a str, &'static str)>,
    cand: Option<(&'a str, &'static str)>,
    base: usize,
) {
    if let Some((slice, name)) = cand {
        let start = slice.as_ptr() as usize - base;
        let replace = match *best {
            Some((incumbent, _)) => start < (incumbent.as_ptr() as usize - base),
            None => true,
        };
        if replace {
            *best = Some((slice, name));
        }
    }
}

/// Return the first `SecretMatch` found in `text`, or `None`.
fn scan(text: &str) -> Option<SecretMatch> {
    let context = EntropyScanContext::new(text);
    scan_from_with_trigger(text, 0, &context).map(|(slice, detector, trigger)| {
        let mut matched = build_match(detector, slice);
        matched.trigger = trigger;
        matched
    })
}

/// A named redact-not-block surface whose contract is intentionally separate
/// from manifest-backed write admission (ADR-115 Amendment 2).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RedactionSurface {
    /// Git ingestion stores only masked commit, issue, and pull-request text.
    GitIngest,
    /// Session mirroring stores only masked `text` and `raw` projections.
    SessionMirror,
    /// MCP diagnostics are bounded caller-visible transport data, not records.
    McpDiagnostic,
    /// The kg `scan` verb's masked preview: caller-visible, never stored.
    GateProbe,
}

/// Whether a redaction surface can consume a secret-gate exemption.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RedactionSurfaceMode {
    /// Always apply the canonical masker; never synthesize a stamp or event.
    PermanentMaskOnly,
}

/// Machine-readable contract for a named redaction surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RedactionSurfaceContract {
    pub mode: RedactionSurfaceMode,
    /// Durable target containing the masked result, if this is a write surface.
    pub final_stored_target: Option<&'static str>,
    /// Reserved stamp location; absent for permanent mask-only surfaces.
    pub stamp_property: Option<&'static str>,
    /// Atomic exemption-success event; absent when admission cannot occur.
    pub atomic_success_event: Option<&'static str>,
}

/// Final stored target for [`RedactionSurface::GitIngest`] — see
/// [`redaction_surface_contract`].
pub const GIT_INGEST_STORED_TARGET: &str = "final git-ingest entity/note fields";

/// Final stored target for [`RedactionSurface::SessionMirror`] — see
/// [`redaction_surface_contract`]. Names every column the session mirror
/// writes a masked provider-export projection into, not just the message
/// body columns. `cwd`/`git_branch` live only on `sessions`, keyed per
/// session — `session_messages` carries no such columns of its own (see the
/// `session_messages` DDL in `khive-pack-session`).
pub const SESSION_MIRROR_STORED_TARGET: &str =
    "session_messages.text, session_messages.raw, sessions.cwd, sessions.git_branch, \
     and sessions.slug";

/// Return the closed contract for a named redact-not-block surface.
pub const fn redaction_surface_contract(surface: RedactionSurface) -> RedactionSurfaceContract {
    let final_stored_target = match surface {
        RedactionSurface::GitIngest => Some(GIT_INGEST_STORED_TARGET),
        RedactionSurface::SessionMirror => Some(SESSION_MIRROR_STORED_TARGET),
        RedactionSurface::McpDiagnostic | RedactionSurface::GateProbe => None,
    };

    RedactionSurfaceContract {
        mode: RedactionSurfaceMode::PermanentMaskOnly,
        final_stored_target,
        stamp_property: None,
        atomic_success_event: None,
    }
}

/// Apply the canonical detector to a named permanent mask-only surface.
///
/// This wrapper makes the non-admission decision executable at each call site:
/// it has no manifest input, cannot return an exemption outcome, and cannot
/// synthesize the runtime-owned `khive:secret_gate` property or success event.
pub fn mask_for_redaction_surface(
    surface: RedactionSurface,
    text: &str,
) -> std::borrow::Cow<'_, str> {
    match redaction_surface_contract(surface).mode {
        RedactionSurfaceMode::PermanentMaskOnly => mask_secrets(text),
    }
}

/// Upper bound on how many characters of a diagnostic-boundary input the
/// canonical masker is ever asked to scan, regardless of a caller's own
/// output cap. Chosen comfortably larger than the largest output cap among
/// the callers of [`mask_bounded`] (1,024, `khive-mcp`'s
/// `MAX_BACKEND_ERROR_MESSAGE_CHARS`) so a credential's terminating span
/// remains inside the window for any message that is itself smaller than the
/// window. Masking cost scales with this constant, never with a caller's raw
/// input length. Shared by every diagnostic-boundary redaction site so the
/// window cannot drift between them independently.
pub const MASK_WINDOW_CHARS: usize = 4_096;

/// Result of [`mask_bounded`]: masked, window- and output-bounded text plus
/// the flags a caller needs to finish assembling a caller-visible
/// diagnostic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BoundedMask {
    /// Masked text, never longer than `output_cap_chars` plus one trailing
    /// truncation-marker character. May be the bare truncation marker alone
    /// when the retained window held a single token longer than the window.
    pub text: String,
    /// True when `text` is not the complete masked input: the raw input
    /// exceeded `window_chars`, the masked window exceeded `output_cap_chars`,
    /// or the window held one token longer than the window that had to be
    /// dropped whole.
    pub truncated: bool,
    /// True when the canonical masker replaced a span inside the retained
    /// window, or the window's only content was dropped whole for being an
    /// oversized single token. A caller that decides whether raw content is
    /// safe to echo back verbatim on this flag must also treat `truncated`
    /// as reason enough on its own — content the window never retained is
    /// exactly as unverified as content the masker redacted.
    pub redacted: bool,
}

/// Bound a diagnostic-boundary masking call to at most `window_chars` of
/// `text` before the canonical masker ever runs, then cap the masked result
/// to `output_cap_chars`. Bounding happens BEFORE masking — not after, as a
/// truncate-then-mask policy would — so scan cost is bounded by
/// `window_chars` regardless of the caller's input length.
///
/// A window cut mid-token would let a masker that never saw the token's
/// terminating shape (e.g. the `@` closing `scheme://user:pass@host`) emit
/// the token's visible prefix unmasked — the exact split-secret hole a prior
/// mask-the-full-input-first policy existed to close, at the cost of
/// unbounded scan work. This function closes the hole without re-widening
/// the window to the input's full length: any token straddling the window
/// boundary is dropped in its entirety (back to the last whitespace inside
/// the window) rather than masked, because a masker can only vouch for a
/// token it saw whole. A single token that is itself longer than the window
/// has no earlier whitespace to fall back to inside the window and is
/// replaced by the truncation marker alone.
///
/// The same drop applies to a chain of bridged fragments straddling the
/// boundary, not just the one partial token touching it: see
/// `trailing_bridge_fragment_cut` (private to this module) for why a
/// forward lookahead cannot bound this instead, and for the backward walk
/// that closes it purely from data already inside the window.
///
/// `window_chars` must be at least `output_cap_chars`; debug builds assert
/// this so a misconfigured call site fails loudly instead of silently
/// capping tighter than it windows, and the cap is additionally clamped to
/// `window_chars` in every build so a misconfigured call site cannot cap
/// tighter than it windows even outside debug assertions.
pub fn mask_bounded(
    surface: RedactionSurface,
    text: &str,
    window_chars: usize,
    output_cap_chars: usize,
) -> BoundedMask {
    debug_assert!(
        window_chars >= output_cap_chars,
        "the input window must stay at least as large as the output cap"
    );
    let output_cap_chars = output_cap_chars.min(window_chars);

    let input_truncated = text.chars().nth(window_chars).is_some();
    let mut window: String = text.chars().take(window_chars).collect();

    if input_truncated {
        match window
            .char_indices()
            .rev()
            .find(|(_, ch)| ch.is_whitespace())
        {
            // Keep the whitespace itself; drop only the partial token after it.
            Some((idx, ch)) => window.truncate(idx + ch.len_utf8()),
            // A single token spans the whole window: nothing can be shown
            // whole, so show nothing at all.
            None => window.clear(),
        }
    }

    if input_truncated && !window.is_empty() {
        if let Some(cut) = trailing_bridge_fragment_cut(&window) {
            window.truncate(cut);
        }
    }

    if input_truncated && window.is_empty() {
        return BoundedMask {
            text: TRUNCATION_MARKER.to_string(),
            truncated: true,
            redacted: true,
        };
    }

    debug_assert!(window.chars().count() <= window_chars);
    let masked = mask_for_redaction_surface(surface, &window);
    let redacted = masked.as_ref() != window.as_str();

    let mut chars = masked.chars();
    let mut bounded: String = chars.by_ref().take(output_cap_chars).collect();
    let output_capped = chars.next().is_some();
    if output_capped || input_truncated {
        bounded.push_str(TRUNCATION_MARKER);
    }

    BoundedMask {
        text: bounded,
        truncated: input_truncated || output_capped,
        redacted,
    }
}

const TRUNCATION_MARKER: &str = "…";

/// Redact every detected secret span in `text`, replacing each with
/// `***MASKED***`.
///
/// This is the masking counterpart to [`check`]: where `check` hard-blocks a
/// write on the first match, `mask_secrets` is for content that must be emitted
/// or stored with credentials stripped. Named Git/session/MCP callers enter it
/// through [`mask_for_redaction_surface`]. It reuses the SAME canonical detector
/// set as `check`/`scan`, so callers must never maintain a second, weaker masker.
///
/// Returns `Cow::Borrowed` when no secret is present (the common case), avoiding
/// an allocation. Spans are discovered left to right against the ORIGINAL text,
/// always evaluating trigger context over the full input — a high-entropy value
/// whose only trigger word sits to the left of an earlier-redacted secret is
/// still detected. Cumulative suffix-scan work is capped; when dense input
/// exhausts the cap after a match, that match is extended through the remaining
/// text so unscanned credentials cannot survive. See
/// `docs/api/secret_gate.md#mask_secrets` for the scan-cursor mechanics.
pub fn mask_secrets(text: &str) -> std::borrow::Cow<'_, str> {
    let (spans, _scan_work_bytes) = collect_mask_spans(text);
    if spans.is_empty() {
        return std::borrow::Cow::Borrowed(text);
    }
    let mut out = String::with_capacity(text.len());
    let mut cursor = 0;
    for (start, end) in spans {
        // Spans are non-overlapping and ascending (each starts at/after the prior
        // `end`); `max(cursor)` is a defensive guard, never load-bearing.
        let start = start.max(cursor);
        out.push_str(&text[cursor..start]);
        out.push_str(REDACTION_MARKER);
        cursor = end.max(cursor);
    }
    out.push_str(&text[cursor..]);
    std::borrow::Cow::Owned(out)
}

/// Collect absolute byte spans to redact and report cumulative scan bytes revisited.
/// Exhausting the work budget extends the last confirmed secret span through the input tail.
fn collect_mask_spans(text: &str) -> (Vec<(usize, usize)>, usize) {
    let base = text.as_ptr() as usize;
    let context = EntropyScanContext::new(text);
    let tokens = &context.tokens;
    // Collect every secret span (absolute byte offsets into `text`) before
    // writing any output, so trigger-context detection always sees the original
    // string rather than the suffix after the previous redaction.
    let mut spans: Vec<(usize, usize)> = Vec::new();
    let mut from = 0;
    let mut scan_work_bytes = 0usize;
    while from < text.len() {
        // Candidate enumeration may revisit the prefix of the original token
        // containing `from`. Charge it as well as the remaining suffix; in a
        // whitespace gap the scan still begins at `from`.
        let token_index = tokens.partition_point(|&(offset, raw)| offset + raw.len() <= from);
        let scan_start = tokens
            .get(token_index)
            .map_or(from, |&(offset, _)| offset.min(from));
        let scan_len = text.len() - scan_start;
        let next_scan_work = scan_work_bytes.saturating_add(scan_len);
        if scan_work_bytes > 0 && next_scan_work > MAX_MASK_SCAN_WORK_BYTES {
            // Every previous sweep ended at a confirmed match; extending that
            // redaction through the remaining tail is fail-closed.
            spans.last_mut().expect("a prior scan found a span").1 = text.len();
            break;
        }
        scan_work_bytes = next_scan_work;
        match scan_from(text, from, &context) {
            Some((sub, _detector)) => {
                let start = sub.as_ptr() as usize - base;
                // The prefix detectors return whitespace-delimited tokens, so a
                // credential glued to structural punctuation (JSON quotes/braces,
                // sentence commas) carries that trailing punctuation into the
                // match. Trim a conservative trailing set that can never be part
                // of a credential, so redacting does not consume surrounding JSON
                // or prose structure. `=` `/` `+` `.` `-` `_` are intentionally
                // NOT trimmed — they are valid base64/JWT/key characters.
                let core_len = sub
                    .trim_end_matches(['"', '\'', '`', '}', ']', ')', ',', ';'])
                    .len();
                let end = extend_across_invisible_bridge(text, start + core_len.max(1));
                push_mask_spans(text, start, end, &mut spans);
                // `scan_from` only returns matches with start >= from, and `end`
                // is strictly greater than `start`, so `from` strictly advances.
                from = end;
            }
            None => break,
        }
    }
    (spans, scan_work_bytes)
}

/// A character that splits a payload without showing anything: non-ASCII and not
/// a letter or digit, so U+200B and its neighbours qualify while the letters of a
/// non-ASCII password do not. The second half of that predicate is load-bearing:
/// `redis://:密码@host` is ONE credential whose characters are non-ASCII, and a
/// rule keyed on non-ASCII alone splits it and prints the password between two
/// redaction markers.
fn is_invisible_bridge_separator(c: char) -> bool {
    !c.is_ascii() && !c.is_alphanumeric()
}

/// Byte offset a redaction must reach when the payload continues past `end`
/// behind an INVISIBLE separator.
///
/// A gap made only of [`is_invisible_bridge_separator`] characters is not something
/// a person types between a credential and the next word; it is how one payload is
/// split so each half falls under a detector's length floor. Detection already
/// reconstructs those chains ([`bridge_fragment_chain`]), but the masker redacted
/// only the token the scan returned, so the rest of the same payload survived into
/// stored text. Gaps holding any ASCII character — the ordinary spaces and newlines
/// between a commit sha and the prose after it — are never walked, so this cannot
/// eat surrounding text.
fn extend_across_invisible_bridge(text: &str, end: usize) -> usize {
    let mut end = end;
    for _ in 1..MAX_BRIDGE_FRAGMENTS {
        let rest = &text[end..];
        let Some(gap_len) = rest.find(|c: char| c.is_ascii_alphanumeric()) else {
            break;
        };
        let gap = &rest[..gap_len];
        if gap.is_empty() || !gap.chars().all(is_invisible_bridge_separator) {
            break;
        }
        let fragment = &rest[gap_len..];
        let fragment_len = fragment
            .find(|c: char| !c.is_ascii_alphanumeric())
            .unwrap_or(fragment.len());
        if fragment_len < MIN_BRIDGE_FRAGMENT_LEN {
            break;
        }
        end += gap_len + fragment_len;
    }
    end
}

/// Push the redaction spans for `text[start..end]`, breaking at
/// [`is_invisible_bridge_separator`] characters so a separator that joined two
/// fragments of one payload stays visible instead of being swallowed into a single
/// marker.
///
/// A span holding no such character — every ordinary credential, base64 and JWT
/// forms included, whose `.` `+` `/` `=` are ASCII, and non-ASCII passwords, whose
/// letters are alphanumeric — is pushed whole, so this changes nothing for them. A
/// span that yields no run at all is pushed whole as well: redacting more than
/// necessary is the safe direction.
fn push_mask_spans(text: &str, start: usize, end: usize, spans: &mut Vec<(usize, usize)>) {
    let span = &text[start..end];
    if !span.chars().any(is_invisible_bridge_separator) {
        spans.push((start, end));
        return;
    }
    let before = spans.len();
    let mut run_start: Option<usize> = None;
    for (offset, ch) in span.char_indices() {
        if is_invisible_bridge_separator(ch) {
            if let Some(run) = run_start.take() {
                spans.push((start + run, start + offset));
            }
        } else {
            run_start.get_or_insert(offset);
        }
    }
    if let Some(run) = run_start {
        spans.push((start + run, end));
    }
    if spans.len() == before {
        spans.push((start, end));
    }
}

/// Maximum characters of raw error text admitted to the masking pass.
///
/// This is NOT a tight bound like [`MAX_LOG_TEXT_OUTPUT_CHARS`] below — it exists only to
/// stop a truly pathological input (gigabytes of attacker-controlled text funneled into one
/// error/log line) from making the masking scan unbounded. It is a pure compute bound, not a
/// safety bound: [`find_url_userinfo`] has no length limit on the password it recognizes, so
/// no finite value of this constant can guarantee a credential never straddles it — a
/// password longer than whatever this is set to always has a crossing case. The actual
/// safety invariant lives in [`redact_crossing_boundary_url_userinfo`], the fallback
/// [`bounded_masked_log_text`] runs after [`mask_secrets`]: it redacts any `scheme://user:`
/// opening whose password run reaches this cut point without a terminating `@`, regardless
/// of how long that password is. 1 MiB just keeps the scan itself cheap.
const MAX_LOG_TEXT_MASK_INPUT_CHARS: usize = 1_048_576;
/// Maximum characters of masked error text emitted to a log record.
const MAX_LOG_TEXT_OUTPUT_CHARS: usize = 1_024;

/// Bound and mask arbitrary error text for log emission.
///
/// Log records are a disclosure surface the same way wire errors are: they are
/// shipped, aggregated, and read by consumers outside the process. Backend
/// error text (gate backends included) can embed connection strings or
/// credentials, so the FULL text (up to `MAX_LOG_TEXT_MASK_INPUT_CHARS`, a
/// pure compute bound — see its doc comment) is masked with the canonical
/// detector set before any truncation happens. Masking after truncation would
/// let a secret whose tail sits past the bound lose the context (e.g. a URL's
/// terminating `@`) a detector needs to recognize it, leaving its head
/// unmasked in the log — truncate-then-mask must never replace
/// mask-then-truncate here. Because `MAX_LOG_TEXT_MASK_INPUT_CHARS` is
/// finite and `find_url_userinfo` has no bound on password length, a
/// password long enough still crosses the cut before its terminating `@`
/// ever appears; `redact_crossing_boundary_url_userinfo` closes that gap
/// by redacting the unterminated opening directly, so no credential prefix
/// survives regardless of secret length. Control (`Cc`), format (`Cf`), line
/// separator (`Zl`), and paragraph separator (`Zp`) Unicode codepoints in the
/// masked text are then escaped: a log line is plain text read by tooling
/// outside this process, and an embedded line break or bidi/format override
/// could forge or visually disguise part of the record. The result is bounded
/// again for the emitted record. A truncation in either the masking pass or the
/// output pass appends `…` so the record declares its own incompleteness.
///
/// This function, not [`mask_for_redaction_surface`], is the direct
/// `mask_secrets` caller for general log-text bounding: it is not one of the
/// three named redact-not-block surfaces (git ingest, session mirror, MCP
/// diagnostics) that surface owns, and its own mask-then-truncate contract —
/// with the additional crossing-boundary fallback above — is a strict
/// superset of what the surface wrapper provides. It lives in this module
/// specifically so it can stay a direct caller; the call-site census in
/// `crates/khive-runtime/tests/adr115_redaction_call_site_census.rs` only
/// requires callers *outside* this file to route through the wrapper.
pub fn bounded_masked_log_text(text: &str) -> String {
    let mask_input_truncated = text.chars().nth(MAX_LOG_TEXT_MASK_INPUT_CHARS).is_some();
    let bounded_input: std::borrow::Cow<'_, str> = if mask_input_truncated {
        std::borrow::Cow::Owned(text.chars().take(MAX_LOG_TEXT_MASK_INPUT_CHARS).collect())
    } else {
        std::borrow::Cow::Borrowed(text)
    };
    let masked = mask_secrets(&bounded_input);
    let masked = if mask_input_truncated {
        redact_crossing_boundary_url_userinfo(&masked)
    } else {
        masked
    };
    let neutralized = neutralize_log_unsafe_chars(&masked);

    let mut chars = neutralized.chars();
    let mut bounded: String = chars.by_ref().take(MAX_LOG_TEXT_OUTPUT_CHARS).collect();
    if chars.next().is_some() || mask_input_truncated {
        bounded.push('…');
    }
    bounded
}

/// Fallback for a `scheme://user:<password>` credential whose password run
/// collided with [`bounded_masked_log_text`]'s truncation of the mask-scan
/// input at [`MAX_LOG_TEXT_MASK_INPUT_CHARS`]. [`find_url_userinfo`] only
/// recognizes a credential once it sees the terminating `@`; when that `@`
/// sits past the truncation point, [`mask_secrets`] never sees the shape at
/// all and the raw `scheme://user:<password prefix>` reaches the log. No
/// finite value of [`MAX_LOG_TEXT_MASK_INPUT_CHARS`] can rule this out — the
/// detector is unbounded, so any cap has a crossing case — so the invariant
/// has to come from this fallback, not from the cap's size.
///
/// Only called when `bounded_masked_log_text` actually truncated the input.
/// It scans `://` occurrences left to right and redacts at the EARLIEST
/// unterminated `user:<password-run>` opening: a colon splits the tail into
/// two non-empty pieces and no `@`, space, or newline appears anywhere from
/// that occurrence to the end of the truncated text. An occurrence whose
/// tail does contain one of those terminators is a complete URL or ordinary
/// prose that ends inside the text (e.g. two URLs logged side by side) and
/// is skipped, not redacted. The anchor must be the earliest such opening,
/// never the last: a later `://` can sit INSIDE the crossing password
/// itself (passwords may contain `://`), and anchoring there would leave
/// the real `user:<password prefix>` before it in the emitted log. From the
/// earliest unterminated opening's colon onward everything is redacted —
/// zero password characters survive, no matter how long the password
/// actually is.
fn redact_crossing_boundary_url_userinfo(text: &str) -> std::borrow::Cow<'_, str> {
    let mut search_from = 0usize;
    while let Some(rel) = text[search_from..].find("://") {
        let scheme_pos = search_from + rel;
        let rest = &text[scheme_pos + 3..];
        let terminated =
            rest.contains('@') || rest.contains(' ') || rest.contains('\n') || rest.contains('\r');
        if !terminated {
            // Same rules as `find_url_userinfo`: the userinfo colon must sit
            // in the authority component (before any `/`, `?`, or `#` — a
            // later colon is path/query text), and only the password must be
            // non-empty (an empty username, `redis://:pass`, is a standard
            // connection-string form and no less a credential). The password
            // run AFTER the colon is unrestricted — a crossing password may
            // itself contain any of those delimiters.
            let authority_end = rest.find(['/', '?', '#']).unwrap_or(rest.len());
            if let Some(colon) = rest[..authority_end].find(':') {
                let pass = &rest[colon + 1..];
                if !pass.is_empty() {
                    let redact_from = scheme_pos + 3 + colon;
                    let mut out = String::with_capacity(redact_from + REDACTION_MARKER.len());
                    out.push_str(&text[..redact_from]);
                    out.push_str(REDACTION_MARKER);
                    return std::borrow::Cow::Owned(out);
                }
            }
        }
        search_from = scheme_pos + 3;
    }
    std::borrow::Cow::Borrowed(text)
}

/// `true` for a Unicode control (`Cc`), format (`Cf`), line separator (`Zl`), or
/// paragraph separator (`Zp`) codepoint, tab excepted.
///
/// Classification is by Unicode general category rather than an ASCII byte range so that
/// multi-byte control/format characters (bidi overrides, zero-width joiners, line/paragraph
/// separators encoded as UTF-8) are caught the same way as single-byte C0 controls like
/// CR/LF — a byte-range check would only ever see the latter. Tab is excepted: it is
/// visually inert in a log line and common in legitimately reformatted prose.
fn is_log_unsafe_char(c: char) -> bool {
    if c == '\t' {
        return false;
    }
    matches!(
        unicode_general_category::get_general_category(c),
        unicode_general_category::GeneralCategory::Control
            | unicode_general_category::GeneralCategory::Format
            | unicode_general_category::GeneralCategory::LineSeparator
            | unicode_general_category::GeneralCategory::ParagraphSeparator
    )
}

/// Escape every [`is_log_unsafe_char`] codepoint in `text` as `\u{XXXX}`.
///
/// Returns `Cow::Borrowed` when nothing needs escaping (the common case), avoiding an
/// allocation. This runs on already-masked text: it must never be skipped for text that
/// bypassed [`mask_secrets`], since a control character can sit inside a would-be secret
/// span and is a distinct disclosure vector from the credential detectors (log injection /
/// forgery, not credential leakage).
fn neutralize_log_unsafe_chars(text: &str) -> std::borrow::Cow<'_, str> {
    if !text.chars().any(is_log_unsafe_char) {
        return std::borrow::Cow::Borrowed(text);
    }
    let mut out = String::with_capacity(text.len());
    for c in text.chars() {
        if is_log_unsafe_char(c) {
            out.push_str(&format!("\\u{{{:04x}}}", c as u32));
        } else {
            out.push(c);
        }
    }
    std::borrow::Cow::Owned(out)
}

// ─── Layer 1: known patterns ─────────────────────────────────────────────────

/// Each entry: (detector_name, needle, min_total_token_len).
///
/// The needle must appear as a word-boundary-adjacent prefix in the token.
/// `min_total_token_len` is the minimum length the token (needle + remainder)
/// must have — prevents the prefix alone triggering without a payload.
const PREFIX_DETECTORS: &[(&str, &str, usize)] = &[
    // AWS
    ("aws-access-key-id", "AKIA", 20),
    ("aws-access-key-id", "ASIA", 20),
    // GitHub tokens: personal-access (ghp_), OAuth (gho_), GitHub App
    // user-to-server (ghu_), server-to-server (ghs_), refresh (ghr_), and the
    // fine-grained PAT (github_pat_). The gh*_ formats carry a 36-character
    // payload; fine-grained PATs carry an 82-character payload.
    ("github-token", "ghp_", 36),
    ("github-token", "gho_", 36),
    ("github-token", "ghu_", 36),
    ("github-token", "ghs_", 36),
    ("github-token", "ghr_", 36),
    ("github-token", "github_pat_", 93),
    // OpenAI project keys carry at least an 80-character payload.
    ("openai-api-key", "sk-proj-", 88),
    // NOTE: bare "sk-" also matches the more-specific prefixes below. Those
    // prefixes retain ownership of their candidates so the generic fallback
    // cannot bypass a vendor-specific minimum.
    // Anthropic
    ("anthropic-api-key", "sk-ant-", 108),
    // Stripe live keys
    ("stripe-secret-key", "sk_live_", 30),
    ("stripe-restricted-key", "rk_live_", 30),
    // Fly.io (fm2_ prefix only — FlyV1 handled separately because it embeds a space)
    ("fly-token", "fm2_", 20),
    // Vercel
    ("vercel-token", "vercel_", 20),
    // Slack
    ("slack-token", "xoxb-", 40),
    ("slack-token", "xoxa-", 40),
    ("slack-token", "xoxp-", 40),
    ("slack-token", "xoxr-", 40),
    ("slack-token", "xoxs-", 40),
    // Age secret key
    ("age-secret-key", "AGE-SECRET-KEY-", 60),
];

/// Known safe compound words that start with `sk-` but are not credentials.
/// E.g. scikit-learn slugs such as `sk-learn`, `sk-image`, `sk-lego`.
const SK_SAFE_PREFIXES: &[&str] = &["sk-learn", "sk-image", "sk-lego", "sk-base", "sk-misc"];

/// Shape-based patterns checked with custom logic.
///
/// Returns the LEFTMOST match across every detector (see [`keep_leftmost`]). The
/// detectors are still offered in priority order, so two detectors that match at
/// the SAME offset (e.g. bare `sk-` and the more-specific `sk-ant-`) resolve to
/// the first-offered one.
fn check_known_patterns(text: &str) -> Option<(&str, &'static str)> {
    let base = text.as_ptr() as usize;
    let mut best: Option<(&str, &'static str)> = None;

    // --- Prefix patterns ---
    for &(name, needle, min_len) in PREFIX_DETECTORS {
        keep_leftmost(
            &mut best,
            find_prefix_token(text, needle, min_len).map(|m| (m, name)),
            base,
        );
    }

    // --- Bare `sk-` (after all more-specific sk- detectors above) ---
    // Require length ≥ 30 AND exclude known safe scikit/library compound words.
    if let Some(token) = find_bare_sk_token(text) {
        keep_leftmost(&mut best, Some((token, "openai-api-key")), base);
    }

    // --- Fly.io FlyV1 token: "FlyV1 <base64-payload>" ---
    // The format embeds a space, so the generic prefix extractor (which stops at
    // whitespace) cannot measure the combined length.  Check for `FlyV1 ` followed
    // by ≥ 4 non-whitespace characters as the payload.
    let mut from = 0;
    while let Some(rel) = text[from..].find("FlyV1 ") {
        let pos = from + rel;
        let at_boundary = pos == 0 || {
            text[..pos]
                .chars()
                .next_back()
                .is_none_or(|c| !c.is_ascii_alphanumeric())
        };
        if at_boundary {
            let payload_start = pos + 6; // skip "FlyV1 "
            let payload = extract_token(&text[payload_start..]);
            if payload.len() >= 4 {
                let candidate = &text[pos..payload_start + payload.len()];
                keep_leftmost(&mut best, Some((candidate, "fly-token")), base);
                break;
            }
        }
        from = pos + "FlyV1 ".len();
    }

    // --- PEM private key block ---
    // "-----BEGIN <TYPE> PRIVATE KEY-----" followed by a body.
    keep_leftmost(
        &mut best,
        find_pem_private_key_block(text).map(|m| (m, "pem-private-key")),
        base,
    );

    // --- JWT triple: eyJ...eyJ...eyJ (header.payload.signature) ---
    // A JWT starts with "eyJ" (base64url of `{"`) and has exactly two dots.
    keep_leftmost(&mut best, find_jwt(text).map(|m| (m, "jwt")), base);

    // --- URL userinfo: scheme://user:pass@host ---
    keep_leftmost(
        &mut best,
        find_url_userinfo(text).map(|m| (m, "url-userinfo")),
        base,
    );

    best
}

/// Locate the first token in `text` that starts with `needle` and has a
/// total length >= `min_len`.  Returns a slice of the full token on match.
fn find_prefix_token<'a>(text: &'a str, needle: &str, min_len: usize) -> Option<&'a str> {
    let mut start = 0;
    while let Some(rel) = text[start..].find(needle) {
        let abs = start + rel;
        // Require that the needle starts at a token boundary (start-of-string
        // or preceded by a non-ASCII-alphanumeric char).  The needles are ASCII,
        // so only an ASCII alphanumeric can be a real continuation of the same
        // token; CJK/accented text (which Rust counts as `is_alphanumeric`) must
        // act as a delimiter, else a secret glued to non-Latin prose (`数据AKIA…`)
        // is missed.
        let at_boundary = abs == 0 || {
            let prev = text[..abs].chars().next_back().unwrap_or(' ');
            !prev.is_ascii_alphanumeric()
        };
        if at_boundary {
            let token = extract_token(&text[abs..]);
            if token.len() >= min_len && !is_filename_shaped_prefix_match(token, needle) {
                return Some(token);
            }
        }
        start = abs + needle.len().max(1);
    }
    None
}

/// Locate a generic `sk-` token without reclassifying a registered vendor
/// prefix that did not meet its own minimum length.
fn find_bare_sk_token(text: &str) -> Option<&str> {
    let base = text.as_ptr() as usize;
    let mut from = 0;
    while from < text.len() {
        let token = find_prefix_token(&text[from..], "sk-", 30)?;
        let belongs_to_specific_detector = PREFIX_DETECTORS
            .iter()
            .any(|&(_, needle, _)| needle.starts_with("sk-") && token.starts_with(needle));
        let is_safe_compound = SK_SAFE_PREFIXES.iter().any(|safe| token.starts_with(safe));
        if !belongs_to_specific_detector && !is_safe_compound {
            return Some(token);
        }

        let token_start = token.as_ptr() as usize - base;
        // Suppress only this `sk-` occurrence. The same whitespace-delimited
        // token may contain a later generic key glued after punctuation, and
        // advancing past the whole token would hide it from the fallback.
        from = token_start + "sk-".len();
    }
    None
}

/// Known source-file extensions that can terminate an ordinary provider-
/// prefixed filename. This is deliberately a closed set: an unknown suffix
/// is not evidence strong enough to suppress a context-free prefix detector.
const SOURCE_FILE_EXTENSIONS: &[&str] =
    &[".py", ".rs", ".ts", ".js", ".sh", ".md", ".toml", ".json"];

/// Returns `true` for a lowercase source filename after a known provider
/// prefix, such as `vercel_deployment_monitor.py`, optionally followed by a
/// source citation's line reference: `vercel_deployment_monitor.py:412` or
/// `vercel_deployment_monitor.py:412-418`.
///
/// A source extension alone is not enough. The payload before it must contain
/// only lowercase ASCII letters and filename/path punctuation; any uppercase
/// letter or digit is credential-value evidence and keeps the prefix match
/// fail-closed. Outer Markdown/prose punctuation is ignored, but never any
/// payload byte inside the filename itself.
///
/// The line reference is a POSITIONALLY DISTINCT suffix, never part of the
/// stem the checks below apply: it is parsed and stripped first, and only
/// then is the extension matched against what remains, so a digit inside the
/// stem itself (`some2module.py`) still fails the all-lowercase check exactly
/// as before.
///
/// A trailing colon with nothing after it stays where it has always been: in
/// the generic prose-punctuation trim just below, which removes it before any
/// of this runs. `<prefix>some_module.py:` in a sentence was admitted before
/// line references were understood here and is still admitted, because it is
/// the same filename it always was with sentence punctuation after it. Adding
/// a line-reference grammar is a widening of what this function accepts; it
/// narrows nothing.
fn is_filename_shaped_prefix_match(token: &str, needle: &str) -> bool {
    let token = token.trim_end_matches(|c: char| {
        matches!(
            c,
            '`' | '"' | '\'' | ')' | ']' | '}' | '>' | ',' | ';' | ':' | '!' | '?'
        )
    });
    let token = token.strip_suffix('.').unwrap_or(token);
    let Some(payload) = token.strip_prefix(needle) else {
        return false;
    };
    let payload = strip_source_citation_line_reference(payload);
    let Some(stem) = SOURCE_FILE_EXTENSIONS
        .iter()
        .find_map(|extension| payload.strip_suffix(extension))
    else {
        return false;
    };

    stem.bytes().any(|byte| byte.is_ascii_lowercase())
        && stem
            .bytes()
            .any(|byte| matches!(byte, b'_' | b'-' | b'/' | b'.'))
        && stem
            .bytes()
            .all(|byte| byte.is_ascii_lowercase() || matches!(byte, b'_' | b'-' | b'/' | b'.'))
}

/// Strip a trailing source citation's line reference from `payload` and
/// return the remainder; returns `payload` unchanged when the tail is not
/// exactly one of these two shapes.
///
/// Grammar: `:<digits>` or `:<digits>-<digits>` — digits only, at least one
/// digit in each run, no leading `+`/`-` on either run, and a single `-`
/// separating the two runs in the range form. A second colon, a non-digit
/// byte, or more than one `-` all mean this is not a line reference, so the
/// caller's extension match declines exactly as it does for any other
/// unrecognized suffix.
///
/// This grammar is intentionally separate from the stem predicate the caller
/// applies after this returns: the reference is peeled off BEFORE the
/// extension is matched, so the digits admitted here never reach the stem,
/// and they do not loosen what that predicate accepts.
fn strip_source_citation_line_reference(payload: &str) -> &str {
    let Some(colon) = payload.rfind(':') else {
        return payload;
    };
    let (head, reference) = (&payload[..colon], &payload[colon + 1..]);

    let is_digit_run = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
    let is_line_reference = match reference.split_once('-') {
        None => is_digit_run(reference),
        Some((start, end)) => is_digit_run(start) && is_digit_run(end),
    };

    if is_line_reference {
        head
    } else {
        payload
    }
}

/// Shortest line of base64 that counts as PEM key material. Real key blocks
/// wrap at 64 columns; the last line of a block can be shorter, but a block
/// with no END marker is recognised by a full-width line, so a short tail on
/// its own is a mention rather than a key.
const PEM_BODY_LINE_MIN: usize = 40;

/// A line consisting only of base64 alphabet characters, long enough to be a
/// wrapped line of a key block.
fn is_pem_body_line(line: &str) -> bool {
    line.len() >= PEM_BODY_LINE_MIN
        && line
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'+' || b == b'/' || b == b'=')
}

/// Byte offset of the first line break at or after `from`: a real newline,
/// or the two-character escape `\\n` that a newline becomes once the text
/// is serialized JSON (a note's properties, a stream payload). Returns the
/// break's start and the offset just past it, or `None` when the rest of
/// the text is one line.
fn next_line_break(text: &str, from: usize) -> Option<(usize, usize)> {
    let rest = &text[from..];
    let real = rest.find('\n').map(|i| (from + i, from + i + 1));
    let escaped = rest.find("\\n").map(|i| (from + i, from + i + 2));
    match (real, escaped) {
        (Some(r), Some(e)) => Some(if r.0 <= e.0 { r } else { e }),
        (r, e) => r.or(e),
    }
}

/// End of the line starting at `from` (exclusive of its break) and the start
/// of the following line.
fn line_bounds(text: &str, from: usize) -> (usize, usize) {
    match next_line_break(text, from) {
        Some((end, next)) => (end, next),
        None => (text.len(), text.len()),
    }
}

/// Find the leftmost PEM private key block: a `-----BEGIN <TYPE> PRIVATE
/// KEY-----` header line followed by a body. The body is either a matching
/// `-----END ... PRIVATE KEY-----` marker before the next BEGIN, or at
/// least one line of base64 of key-block width directly under it. A header
/// with neither is a mention of the format (a documentation page, code that
/// prints the label) and carries no key, so it is not a candidate. Lines
/// break on a newline or on its JSON escape, so a key inside a serialized
/// document is read the same way as one in plain text. The returned slice
/// is bounded to the block: through the END line when one is present,
/// otherwise through the last base64 line under the header.
fn find_pem_private_key_block(text: &str) -> Option<&str> {
    let mut search = 0;
    while let Some(rel) = text[search..].find("-----BEGIN") {
        let pos = search + rel;
        let (header_end, body_start) = line_bounds(text, pos);
        let header = &text[pos..header_end];
        // Resume after this header on the next pass whatever it turns out to be.
        search = header_end;
        if !header.contains("PRIVATE KEY-----") {
            continue;
        }
        // The END marker must belong to this header: stop looking at the
        // next BEGIN so a mention above a real block does not claim it.
        let next_begin = text[body_start..]
            .find("-----BEGIN")
            .map(|r| body_start + r)
            .unwrap_or(text.len());
        if let Some(end_rel) = text[body_start..next_begin].find("-----END") {
            let end_pos = body_start + end_rel;
            let (end_line, end_next) = line_bounds(text, end_pos);
            if text[end_pos..end_line].contains("PRIVATE KEY-----") {
                return Some(&text[pos..end_next]);
            }
        }
        let mut body_end = None;
        let mut cursor = body_start;
        while cursor < text.len() {
            let (line_end, next) = line_bounds(text, cursor);
            let line = text[cursor..line_end]
                .trim_end_matches('\r')
                .trim_end_matches("\\r");
            if is_pem_body_line(line) {
                body_end = Some(next);
                cursor = next;
                continue;
            }
            // The last line of a wrapped block is usually shorter than the
            // others. Once at least one full-width line has been seen, a
            // trailing base64-only run of any length belongs to the block,
            // so a masked surface never keeps the tail of the key. Inside a
            // serialized JSON string that run ends at the closing quote
            // instead of a line break; the block ends where the run ends.
            let run = line
                .bytes()
                .take_while(|b| b.is_ascii_alphanumeric() || *b == b'+' || *b == b'/' || *b == b'=')
                .count();
            let whole_line = run == line.len();
            let json_end = line[run..].starts_with('"');
            if run > 0 && (whole_line || json_end) {
                if body_end.is_some() {
                    body_end = Some(if whole_line { next } else { cursor + run });
                } else if run >= PEM_BODY_LINE_MIN && json_end {
                    body_end = Some(cursor + run);
                }
            }
            break;
        }
        if let Some(end) = body_end {
            return Some(&text[pos..end]);
        }
    }
    None
}

/// Scan for a JWT pattern: at least two "eyJ" segments separated by a `.`
/// character, with each segment at least 10 chars.
fn find_jwt(text: &str) -> Option<&str> {
    let bytes = text.as_bytes();
    let mut i = 0;
    while i + 4 < bytes.len() {
        if bytes[i..].starts_with(b"eyJ") {
            // Find the end of this JWT (whitespace or string end).
            let end = bytes[i..]
                .iter()
                .position(|&b| b == b' ' || b == b'\n' || b == b'\r' || b == b'\t')
                .map(|p| i + p)
                .unwrap_or(bytes.len());
            let candidate = &text[i..end];
            // Must have at least 2 dots and 3 eyJ-prefixed segments.
            let dots = candidate.as_bytes().iter().filter(|&&b| b == b'.').count();
            if dots >= 2 {
                let parts: Vec<&str> = candidate.splitn(3, '.').collect();
                if parts.len() == 3
                    && parts[0].starts_with("eyJ")
                    && parts[1].starts_with("eyJ")
                    && parts[0].len() >= 10
                    && parts[1].len() >= 10
                {
                    return Some(candidate);
                }
            }
            i = end + 1;
        } else {
            i += 1;
        }
    }
    None
}

/// Detect `scheme://user:pass@host` patterns where the userinfo carries an
/// actual credential: a non-empty password. The username may be empty —
/// `redis://:secret@host` is a standard empty-user connection string and its
/// password is no less a credential for the missing username.
fn find_url_userinfo(text: &str) -> Option<&str> {
    let mut search = text;
    let mut base = 0usize;
    while let Some(at_rel) = search.find("://") {
        let at_abs = base + at_rel;
        // After `://`, only the authority component may carry userinfo: it
        // ends at the first `/`, `?`, `#`, space, or newline. An `@` past
        // that boundary is path/query text (`https://host/a:x@next`), not a
        // credential.
        let rest_start = at_abs + 3;
        let rest = &text[rest_start..];
        let authority_end = rest
            .find(['/', '?', '#', ' ', '\n', '\r'])
            .unwrap_or(rest.len());
        if let Some(at_pos) = rest[..authority_end].rfind('@') {
            let userinfo = &rest[..at_pos];
            // Must contain a colon with a non-empty password after it.
            if let Some(colon) = userinfo.find(':') {
                let pass = &userinfo[colon + 1..];
                if !pass.is_empty() {
                    // Return a slice starting from the scheme.  Walk back from
                    // `at_abs` to the first non-scheme char and resume just past
                    // it.  Use `char_indices` and skip by the separator's full
                    // UTF-8 width: a multibyte separator (e.g. CJK prose before a
                    // credential URL) would otherwise leave `scheme_start` inside
                    // the codepoint and panic the slice below.
                    let scheme_start = text[..at_abs]
                        .char_indices()
                        .rev()
                        .find(|(_, c)| {
                            !c.is_ascii_alphanumeric() && *c != '+' && *c != '-' && *c != '.'
                        })
                        .map(|(idx, c)| idx + c.len_utf8())
                        .unwrap_or(0);
                    // Ensure there are no spaces in userinfo (not a code snippet).
                    if !userinfo.contains(' ') && !userinfo.contains('\n') {
                        let end = rest_start
                            + at_pos
                            + 1
                            + rest[at_pos + 1..]
                                .find([' ', '\n', '\r'])
                                .unwrap_or(rest[at_pos + 1..].len());
                        return Some(&text[scheme_start..end.min(text.len())]);
                    }
                }
            }
        }
        base = at_abs + 3;
        search = &text[base..];
    }
    None
}

// ─── Layer 2: entropy heuristic ─────────────────────────────────────────────

/// Trigger words checked as a bounded standalone word (see
/// [`contains_bounded_word`]). `token` is deliberately excluded — see
/// `has_standalone_token`/`has_token_assignment` instead.
/// See `docs/api/secret_gate.md#trigger_words` for the substring-collision
/// rationale (issues #577 / #632).
const TRIGGER_WORDS: &[&str] = &[
    "key",
    "secret",
    "password",
    "passwd",
    "credential",
    "bearer",
    "auth",
    "apikey",
];

/// Compound triggers that retain suffix matching inside credential labels.
/// Their underscore separator disambiguates them from ordinary prose, and
/// suffixes are common in versioned credential names such as `api_keyv2`.
const COMPOUND_TRIGGER_WORDS: &[&str] = &["api_key", "access_key", "private_key"];

/// Minimum token length to apply the entropy check.
const MIN_ENTROPY_LEN: usize = 24;

/// Shannon entropy threshold (bits per character) above which a token is
/// considered high-entropy.  7.0 corresponds to ~99% utilisation of a
/// 128-symbol alphabet — typical for random base64/hex.
const ENTROPY_THRESHOLD: f64 = 4.5;

/// Window around a trigger word in which a high-entropy token must appear.
const TRIGGER_WINDOW: usize = 120;

/// Credential-shaped exact hex lengths (AWS secret key, SHA-256/git SHA
/// doubled, SHA-512 hex, etc.) — checked against a whole token, a single
/// separator-delimited run, and a normalized (separator-stripped)
/// concatenation of adjacent hex runs/tokens; see
/// [`normalized_hex_credential_span`].
const HEX_CREDENTIAL_LENGTHS: &[usize] = &[32, 40, 64, 128];

/// Max fragments [`bridge_fragment_chain`] concatenates per credential (fragment-count bound,
/// not gap byte length — see docs/api/secret_gate.md#bridge-fragment-reconstruction).
const MAX_BRIDGE_FRAGMENTS: usize = 6;

/// Max delimiter-only glue tokens absorbed per direction while bridging fragments; see
/// docs/api/secret_gate.md#bridge-fragment-reconstruction.
const MAX_BRIDGE_GLUE_TOKENS: usize = 6;

/// Shortest bare token treated as a plausible bridge fragment; see
/// docs/api/secret_gate.md#bridge-fragment-reconstruction.
const MIN_BRIDGE_FRAGMENT_LEN: usize = 8;

/// Largest index `<= i` that lies on a UTF-8 char boundary of `s`. Stable
/// replacement for the unstable `str::floor_char_boundary`; used to snap
/// byte-offset windows that may land inside a multibyte char before slicing.
fn floor_char_boundary(s: &str, i: usize) -> usize {
    let mut i = i.min(s.len());
    while i > 0 && !s.is_char_boundary(i) {
        i -= 1;
    }
    i
}

/// Tokenize the full input once for the entropy detector. The returned offsets
/// are absolute offsets into `text` and remain valid for every scan cursor.
fn tokenize_entropy_tokens(text: &str) -> Vec<(usize, &str)> {
    #[cfg(test)]
    ENTROPY_TOKENIZATION_COUNT.with(|count| count.set(count.get() + 1));

    // Tokenize into maximal ASCII non-whitespace runs; non-ASCII chars are also
    // delimiters (see docs/api/secret_gate.md#module-level-detection-algorithm,
    // "non-ASCII token delimiting"). Identical to `split_ascii_whitespace` on
    // pure-ASCII input.
    text.split(|c: char| c.is_ascii_whitespace() || !c.is_ascii())
        .filter(|t| !t.is_empty())
        .map(|t| {
            let offset = t.as_ptr() as usize - text.as_ptr() as usize;
            (offset, t)
        })
        .collect()
}

#[derive(Clone, Copy)]
struct JsonScalarContext {
    value_start: usize,
    end: usize,
    label: Option<(usize, &'static str)>,
}

struct EntropyScanContext<'a> {
    tokens: Vec<(usize, &'a str)>,
    scalars: Vec<JsonScalarContext>,
}

impl<'a> EntropyScanContext<'a> {
    fn new(text: &'a str) -> Self {
        Self {
            tokens: tokenize_entropy_tokens(text),
            scalars: json_scalar_contexts(text),
        }
    }

    fn scalar_for(&self, text: &str, value: &str) -> Option<JsonScalarContext> {
        let value = wrapper_strip_repeated(value);
        if value.is_empty() {
            return None;
        }
        let start = value.as_ptr() as usize - text.as_ptr() as usize;
        let end = start + value.len();
        let index = self.scalars.partition_point(|scalar| scalar.end <= start);
        self.scalars
            .get(index)
            .copied()
            .filter(|scalar| end > scalar.value_start && end <= scalar.end)
    }
}

// Validate once before interpreting punctuation as field boundaries. The
// iterative source walk retains offsets for masking; decoding keys prevents
// JSON escapes from hiding an owning credential label.
fn json_scalar_contexts(text: &str) -> Vec<JsonScalarContext> {
    if !text.trim_start().starts_with(['{', '['])
        || serde_json::from_str::<serde::de::IgnoredAny>(text).is_err()
    {
        return Vec::new();
    }
    let bytes = text.as_bytes();
    let mut scalars = Vec::new();
    let mut containers: Vec<Option<(usize, &'static str)>> = Vec::new();
    let mut pending_label = None;
    let mut index = 0;
    while index < bytes.len() {
        match bytes[index] {
            b'{' | b'[' => {
                let label = pending_label
                    .take()
                    .or_else(|| containers.last().copied().flatten());
                containers.push(label);
                index += 1;
            }
            b'}' | b']' => {
                containers.pop();
                pending_label = None;
                index += 1;
            }
            b',' | b':' | b' ' | b'\t' | b'\r' | b'\n' => index += 1,
            _ => {
                let start = index;
                let quoted = bytes[index] == b'"';
                let value_start = start + usize::from(quoted);
                let end = if quoted {
                    index += 1;
                    while index < bytes.len() && bytes[index] != b'"' {
                        index += if bytes[index] == b'\\' { 2 } else { 1 };
                    }
                    let end = index;
                    index += 1;
                    end
                } else {
                    while index < bytes.len()
                        && !bytes[index].is_ascii_whitespace()
                        && !matches!(bytes[index], b',' | b'}' | b']')
                    {
                        index += 1;
                    }
                    index
                };
                if index > bytes.len() {
                    return Vec::new();
                }
                if quoted && text[index..].trim_start().starts_with(':') {
                    let Ok(key) = serde_json::from_str::<String>(&text[start..index]) else {
                        return Vec::new();
                    };
                    let label =
                        find_trigger(&format!("{key}:"), true).map(|trigger| (end, trigger));
                    pending_label = label;
                    continue;
                }
                let label = pending_label
                    .take()
                    .or_else(|| containers.last().copied().flatten());
                scalars.push(JsonScalarContext {
                    value_start,
                    end,
                    label,
                });
            }
        }
    }
    scalars
}

// A bare Git-length value uses line-local context. The preceding label line
// remains authoritative when it explicitly ends in an assignment delimiter.
// Bridge anchors retain full-window context so masking cannot leave a fragment behind.
fn entropy_trigger(
    text: &str,
    tokens: &[(usize, &str)],
    index: usize,
    credential_label_only: bool,
    candidate: EntropyCandidate<'_>,
) -> Option<&'static str> {
    let (mut offset, raw) = tokens[index];
    let mut token_end = offset + raw.len();
    if let Some(scalar) = candidate.scalar {
        offset =
            (candidate.value.as_ptr() as usize - text.as_ptr() as usize).max(scalar.value_start);
        token_end = (candidate.value.as_ptr() as usize - text.as_ptr() as usize
            + candidate.value.len())
        .min(scalar.end);
    }
    let mut window_start = floor_char_boundary(text, offset.saturating_sub(TRIGGER_WINDOW));
    let mut window_end = floor_char_boundary(text, token_end + TRIGGER_WINDOW);
    if let Some(scalar) = candidate.scalar {
        window_start = window_start.max(scalar.value_start);
        window_end = window_end.min(scalar.end);
    }
    let token = strip_delimiters(raw);
    let standalone_revision = token.len() == 40
        && token.bytes().all(|b| b.is_ascii_hexdigit())
        && bridge_fragment_chain(tokens, text, index).len() == 1;
    let (start, end, preceding_label) = if standalone_revision {
        let line_start = text[window_start..offset]
            .rfind(['\r', '\n'])
            .map_or(window_start, |i| window_start + i + 1);
        let line_end = text[token_end..window_end]
            .find(['\r', '\n'])
            .map_or(window_end, |i| token_end + i);
        let before_line = &text[window_start..line_start];
        let previous = before_line
            .strip_suffix("\r\n")
            .or_else(|| before_line.strip_suffix(['\r', '\n']))
            .unwrap_or("");
        let previous_start = previous.rfind(['\r', '\n']).map_or(0, |i| i + 1);
        let previous = previous[previous_start..].trim_end();
        let label = if previous.ends_with([':', '=']) {
            find_trigger(previous, credential_label_only)
        } else {
            None
        };
        (
            line_start.max(window_start),
            line_end.min(window_end),
            label,
        )
    } else {
        (window_start, window_end, None)
    };
    // Trigger context stops at a sentence boundary: a detector name or an
    // unrelated clause in the preceding sentence is not context for this token
    // (issue #2056). The preceding-label fallback is exempt because that line
    // was already required to end in an assignment delimiter.
    find_trigger(
        after_last_sentence_boundary(&text[start..offset]),
        credential_label_only,
    )
    .or_else(|| {
        find_trigger(
            before_first_sentence_boundary(&text[token_end..end]),
            credential_label_only,
        )
    })
    .or(candidate.inline_trigger)
    .or(preceding_label)
}

/// An entropy view with an assignment context bounded to one inline member.
#[derive(Clone, Copy)]
struct EntropyCandidate<'a> {
    value: &'a str,
    member: &'a str,
    inline_trigger: Option<&'static str>,
    bridge_anchor: bool,
    scalar: Option<JsonScalarContext>,
}

fn entropy_candidates(raw: &str) -> Vec<EntropyCandidate<'_>> {
    let mut candidates = Vec::new();
    // Preserve external-window reconstruction across punctuation. This view
    // deliberately supplies no inline label from anywhere in the token.
    if raw.contains([',', ';', '&']) {
        candidates.push(EntropyCandidate {
            value: raw,
            member: raw,
            inline_trigger: None,
            bridge_anchor: true,
            scalar: None,
        });
    }
    for member in raw
        .split([',', ';', '&'])
        .filter(|member| !member.is_empty())
    {
        let has_assignment = member.contains([':', '=']);
        candidates.push(EntropyCandidate {
            value: member,
            member,
            inline_trigger: (!has_assignment)
                .then(|| inline_credential_trigger(member))
                .flatten(),
            bridge_anchor: member.len() == raw.len(),
            scalar: None,
        });
        if !has_assignment {
            continue;
        }
        // An underscore carrier is still a value when an enclosing benign
        // assignment or trailing base64 padding introduces delimiters. Bound
        // this fallback to its own segment so a later label cannot govern an
        // earlier unrelated value.
        for segment in member.split([':', '=']) {
            if let Some(inline_trigger) = inline_credential_trigger(segment) {
                candidates.push(EntropyCandidate {
                    value: wrapper_strip_repeated(segment),
                    member,
                    inline_trigger: Some(inline_trigger),
                    bridge_anchor: false,
                    scalar: None,
                });
            }
        }
        let low = member.to_ascii_lowercase();
        let mut assignment_start = 0;
        for (offset, separator) in member.char_indices() {
            if !matches!(separator, ':' | '=') {
                continue;
            }
            let end = offset + separator.len_utf8();
            let inline_trigger = assignment_credential_trigger(&low[assignment_start..end]);
            assignment_start = end;
            if inline_trigger.is_none() {
                continue;
            }
            let value = wrapper_strip_repeated(&member[end..]);
            if value.is_empty() {
                continue;
            }
            // The first credential assignment governs this member's remaining
            // value, including nested carriers. Exact UUID/hash extraction
            // still tries every suffix via `value_candidates`; the run and
            // reconstruction checks see the entire governed value as before.
            candidates.push(EntropyCandidate {
                value,
                member,
                inline_trigger,
                bridge_anchor: member.len() == raw.len(),
                scalar: None,
            });
            break;
        }
    }
    candidates
}

/// Preserve the original bounded bridge walk while clipping inline context
/// at sibling-member boundaries and the governing value's start. A later
/// assignment cannot use an earlier value as its bridge anchor. External-window
/// candidates retain the original token and its unchanged bridge reconstruction.
fn entropy_bridge_fragments<'a>(
    tokens: &[(usize, &'a str)],
    text: &'a str,
    index: usize,
    candidate: EntropyCandidate<'a>,
) -> Vec<&'a str> {
    let fragments = bridge_fragment_chain(tokens, text, index);
    if candidate.inline_trigger.is_none() {
        return fragments;
    }
    let raw = tokens[index].1;
    let raw_start = raw.as_ptr() as usize;
    let raw_end = raw_start + raw.len();
    let value_start = candidate.value.as_ptr() as usize;
    let member_end = candidate.member.as_ptr() as usize + candidate.member.len();
    fragments
        .into_iter()
        .filter_map(|fragment| {
            let start = fragment.as_ptr() as usize;
            if (raw_start..raw_end).contains(&start) {
                Some(strip_delimiters(candidate.value))
            } else if (start < raw_start && value_start == raw_start)
                || (start >= raw_end && member_end == raw_end)
            {
                Some(fragment)
            } else {
                None
            }
        })
        .collect()
}

/// `from` limits returned spans; context remains relative to each original
/// whitespace token, including when masking resumes inside one member.
fn check_entropy_heuristic<'a>(
    text: &'a str,
    from: usize,
    context: &EntropyScanContext<'a>,
) -> Option<(&'a str, &'static str, Option<&'static str>)> {
    let tokens = &context.tokens;
    let first_token = tokens.partition_point(|&(offset, raw)| offset + raw.len() <= from);
    for (idx, &(context_offset, raw)) in tokens.iter().enumerate().skip(first_token) {
        let token = strip_delimiters(raw);
        if token.len() < MIN_ENTROPY_LEN && !is_bridge_fragment_shape(token) {
            continue;
        }
        let mut best: Option<(&str, &'static str, Option<&'static str>)> = None;
        for mut candidate in entropy_candidates(raw) {
            candidate.scalar = context.scalar_for(text, candidate.value);
            if candidate.scalar.is_none() && !context.scalars.is_empty() {
                let core = wrapper_strip_repeated(candidate.value);
                let start = core.as_ptr() as usize - text.as_ptr() as usize;
                let end = start + core.len();
                let first = context
                    .scalars
                    .partition_point(|scalar| scalar.end <= start);
                if context
                    .scalars
                    .get(first)
                    .is_some_and(|scalar| scalar.value_start < end && scalar.end < end)
                {
                    // The member views below still scan each value; a raw
                    // bridge anchor spanning sibling scalars has no shared label.
                    continue;
                }
            }
            if let Some(scalar) = candidate.scalar {
                let offset = candidate.value.as_ptr() as usize - text.as_ptr() as usize;
                let label = scalar
                    .label
                    .filter(|(end, _)| offset.saturating_sub(*end) <= TRIGGER_WINDOW)
                    .map(|(_, trigger)| trigger);
                candidate.inline_trigger = candidate.inline_trigger.or(label);
            }
            let offset = candidate.value.as_ptr() as usize - text.as_ptr() as usize;
            if offset + candidate.value.len() <= from {
                continue;
            }
            if let Some(found) =
                check_entropy_candidate(text, from, tokens, idx, context_offset, candidate)
            {
                if best
                    .as_ref()
                    .is_none_or(|current| found.0.as_ptr() < current.0.as_ptr())
                {
                    best = Some(found);
                }
            }
        }
        if best.is_some() {
            return best;
        }
    }
    None
}

fn check_entropy_candidate<'a>(
    text: &'a str,
    from: usize,
    tokens: &[(usize, &'a str)],
    idx: usize,
    context_offset: usize,
    candidate: EntropyCandidate<'a>,
) -> Option<(&'a str, &'static str, Option<&'static str>)> {
    let raw_token = candidate.value;
    // Strip common delimiters that wrap the actual value.
    let original_offset = raw_token.as_ptr() as usize - text.as_ptr() as usize;
    let remaining = &raw_token[from.saturating_sub(original_offset).min(raw_token.len())..];
    let token = strip_delimiters(remaining);
    // Only RETURN tokens at or after `from` (already-redacted spans lie
    // before it); the trigger window below still spans the full text.
    let token_offset = token.as_ptr() as usize - text.as_ptr() as usize;
    if token_offset < from {
        return None;
    }
    // A token below MIN_ENTROPY_LEN still passes through when it's a plausible
    // bridge FRAGMENT (see docs/api/secret_gate.md#bridge-fragment-reconstruction);
    // gating on alphanumeric runs (not hex-only) covers base64/base64url halves too.
    let is_bridge_candidate = is_bridge_fragment_shape(token);
    if token.len() < MIN_ENTROPY_LEN && !is_bridge_candidate {
        return None;
    }

    // `token` is ASCII here (non-ASCII was split out at tokenization), so
    // `shannon_entropy` over its bytes is a true per-character entropy.

    // Compute the trigger window before any shape-based allowlist decision.
    // UUIDs require credential-label context rather than a generic mention
    // of `token`; base64 content-hash exemptions remain trigger-sensitive.
    // VCS revisions and file paths use narrower syntactic context below.
    let trigger = entropy_trigger(text, tokens, idx, false, candidate);
    let near_trigger = trigger.is_some();
    let uuid_trigger = entropy_trigger(text, tokens, idx, true, candidate);
    let uuid_near_credential_label = uuid_trigger.is_some();

    // Step 1 (see doc: per-token flagging sequence). UUIDs fall through only
    // beside an explicit credential label; the generic word `token` remains
    // trigger context for opaque values but is common in design prose. Content
    // hashes retain the broader trigger rule. Hex-shaped entropy alone (<=4.0
    // bits/char) can never reach ENTROPY_THRESHOLD.
    let has_uuid_candidate = value_candidates(token).any(is_uuid_canonical);
    if uuid_near_credential_label && has_uuid_candidate {
        return Some((token, "uuid-near-trigger", uuid_trigger));
    }
    if near_trigger && value_candidates(token).any(is_base64_content_hash) {
        return Some((token, "content-hash-near-trigger", trigger));
    }
    if !uuid_near_credential_label && is_uuid_canonical(token) {
        return None;
    }
    if !near_trigger && is_base64_content_hash(token) {
        return None;
    }

    // Step 2. Pure hex off-trigger is allowlisted; trigger-adjacent hex needs an
    // explicit VCS coordinate marker (see doc).
    if !near_trigger && is_pure_hex(token) {
        return None;
    }

    // A fixed-width SHA-256 digest has an independent, explicit source label.
    // Defer its admission until after bridge reconstruction: a digest-shaped
    // fragment must still be checked as part of a larger candidate.
    let labeled_sha256_digest = near_trigger
        && candidate.inline_trigger.is_none()
        && is_labeled_sha256_digest(text, token_offset, token);

    // VCS-marker exemption is a flag over the hex-credential-shape checks only,
    // never an early skip of fragment reconstruction below (see doc).
    if is_vcs_marker_before_hex(text, candidate.member)
        && !has_clause_credential_label_with_inline(
            text,
            context_offset,
            candidate.inline_trigger.is_some(),
            ClauseValueKind::VcsReference,
        )
    {
        return None;
    }

    let repository_revision_reference = is_repository_revision_reference(candidate.member);
    let vcs_reference_exempt = if repository_revision_reference {
        !has_direct_repository_credential_label_with_inline(
            text,
            context_offset,
            candidate.inline_trigger.is_some(),
        )
    } else {
        is_git_revision_reference(text, context_offset, candidate.member)
            && !has_clause_credential_label_with_inline(
                text,
                context_offset,
                candidate.inline_trigger.is_some(),
                ClauseValueKind::VcsReference,
            )
    };

    // Dense mathematical notation has the same mixed-character entropy
    // profile as an opaque token. Exempt a syntactically recognizable
    // LaTeX fragment only when it contains no credential-shaped run and
    // the immediately preceding field does not label it as a credential
    // (#1988). Known-prefix detectors have already run before this layer.
    if near_trigger
        && is_latex_fragment_without_credential_run(token)
        && !(candidate.inline_trigger.is_some()
            || has_immediate_credential_label(text, context_offset))
    {
        return None;
    }

    // Step 3. Hex API keys aren't caught by the entropy heuristic (hex tops out at
    // 4.0 bits/char, below ENTROPY_THRESHOLD 4.5); flag credential-shaped hex directly.
    if !vcs_reference_exempt
        && near_trigger
        && !labeled_sha256_digest
        && is_pure_hex(token)
        && HEX_CREDENTIAL_LENGTHS.contains(&token.len())
    {
        return Some((token, "hex-credential-token", trigger));
    }

    // Step 4 (issue #1044): a credential can dilute below the whole-token-average
    // checks above via low-entropy filler sharing its whitespace token
    // (`vault/<payload>/rotate.md`); re-check each `/`-split run independently.
    // See doc for the #1040 corpus rationale behind the MIN_ENTROPY_LEN floor.
    if near_trigger {
        // vcs_reference_exempt also covers single-token forms below (`rev:<hex>`);
        // it does not cover fragment reconstruction.
        for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
            if run.len() < MIN_ENTROPY_LEN {
                continue;
            }
            if !vcs_reference_exempt
                && !labeled_sha256_digest
                && is_pure_hex(run)
                && HEX_CREDENTIAL_LENGTHS.contains(&run.len())
            {
                return Some((run, "hex-credential-token", trigger));
            }
            if shannon_entropy(run.as_bytes()) >= ENTROPY_THRESHOLD {
                return Some((token, "high-entropy-token", trigger));
            }
        }

        // Step 5 (#1062): concatenate consecutive pure-hex runs (dropping
        // separators) and re-check against HEX_CREDENTIAL_LENGTHS — catches a
        // hex payload split into multiple sub-floor runs. See doc.
        if !vcs_reference_exempt && !labeled_sha256_digest {
            if let Some(candidate) = normalized_hex_credential_span(token) {
                return Some((candidate, "hex-credential-token", trigger));
            }
        }

        // Step 6 (#1062, Unicode variant): bridge fragments split across non-ASCII
        // tokenizer delimiters (e.g. U+200B) via `bridge_fragment_chain`, which walks
        // both directions across a bounded chain (MAX_BRIDGE_FRAGMENTS,
        // MAX_BRIDGE_GLUE_TOKENS) rather than one adjacent pair — see
        // docs/api/secret_gate.md#check_entropy_heuristic--per-token-flagging-sequence
        // for the exact guarantee and its accepted residual (same-uid-host) limits.
        if !vcs_reference_exempt
            && (candidate.bridge_anchor || candidate.inline_trigger.is_some())
            && tokens.len() > 1
        {
            let fragments = entropy_bridge_fragments(tokens, text, idx, candidate);
            if fragments.len() > 1 {
                let first = fragments[0];
                let last = fragments[fragments.len() - 1];
                let chain_start = first.as_ptr() as usize - text.as_ptr() as usize;
                let chain_end = last.as_ptr() as usize - text.as_ptr() as usize + last.len();
                let search_start = chain_start.max(from);
                if let Some(candidate) =
                    normalized_hex_credential_span(&text[search_start..chain_end])
                {
                    return Some((candidate, "hex-credential-token", trigger));
                }
                let concatenated: String = fragments.concat();
                if concatenated.len() >= MIN_ENTROPY_LEN
                    && concatenated.bytes().all(|b| b.is_ascii_alphanumeric())
                    && shannon_entropy(concatenated.as_bytes()) >= ENTROPY_THRESHOLD
                {
                    return Some((token, "high-entropy-token", trigger));
                }
            }
        }

        if is_plausible_file_path(token)
            && !has_clause_credential_label_with_inline(
                text,
                context_offset,
                candidate.inline_trigger.is_some(),
                ClauseValueKind::FilePath,
            )
        {
            return None;
        }

        // Step 8. These shapes are references in technical prose. The prefix, per-run,
        // normalized-hex, and bridge detectors above retain priority over
        // them; an opaque value inside any of those carriers still refuses.
        if labeled_sha256_digest
            || is_prose_code_reference(candidate.member, token)
            || is_environment_name(token)
            || is_latex_prose_macro(token)
            || is_aws_resource_name(token)
        {
            return None;
        }
    }

    // Canonical repository links and href commit targets are source
    // coordinates, not standalone values. The direct-label guard above
    // keeps `api key: <revision URL>` fail-closed; technical prose such as
    // `key-scoped source` can safely retain the citation (#2076).
    if vcs_reference_exempt {
        return None;
    }

    // Step 9: structured-identifier exemption, off-trigger only. Must run after the
    // UUID/hex checks and before the entropy computation (an identifier can exceed
    // ENTROPY_THRESHOLD on Shannon entropy alone).
    if !near_trigger && is_structured_identifier(token) {
        return None;
    }

    let entropy = shannon_entropy(token.as_bytes());
    if entropy < ENTROPY_THRESHOLD {
        return None;
    }

    // High-entropy token in trigger context — flag it.
    if near_trigger {
        return Some((token, "high-entropy-token", trigger));
    }
    None
}

/// `true` when every byte of `run` is an ASCII hex digit. The
/// no-minimum-length, no-`0x`-prefix building block for
/// [`normalized_hex_credential_span`]'s intra-token run decomposition.
/// Unlike [`is_pure_hex`] this has no 8-char floor of its own — a legitimate
/// credential split across separators can leave a shorter individual run
/// that still must sum correctly with its neighbors.
fn is_hex_run(run: &str) -> bool {
    !run.is_empty() && run.bytes().all(|b| b.is_ascii_hexdigit())
}

const VCS_MARKERS: &[&str] = &["commit", "revision", "rev", "sha"];

/// Marker-word form of a VCS reference: `raw_token` is itself a bare marker
/// and the next token in `text` is a 40-hex value.
fn is_vcs_marker_before_hex(text: &str, raw_token: &str) -> bool {
    let token = wrapper_strip_repeated(raw_token);
    let marker = strip_delimiters(token);
    if !VCS_MARKERS
        .iter()
        .any(|candidate| marker.eq_ignore_ascii_case(candidate))
    {
        return false;
    }
    let raw_offset = raw_token.as_ptr() as usize - text.as_ptr() as usize;
    let next = text[raw_offset + raw_token.len()..].trim_start();
    let next = wrapper_strip_repeated(extract_token(next));
    next.len() == 40 && next.bytes().all(|b| b.is_ascii_hexdigit())
}

fn is_git_revision_reference(text: &str, token_offset: usize, raw_token: &str) -> bool {
    const MARKERS: &[&str] = VCS_MARKERS;

    let token = wrapper_strip_repeated(raw_token);
    if is_vcs_marker_before_hex(text, raw_token) {
        return true;
    }

    if token.len() == 40 && token.bytes().all(|b| b.is_ascii_hexdigit()) {
        let marker = trailing_identifier(&text[..token_offset]);
        return MARKERS
            .iter()
            .any(|candidate| marker.eq_ignore_ascii_case(candidate));
    }

    let Some((label, value)) = token.rsplit_once(':') else {
        return false;
    };
    let label = wrapper_strip_repeated(label);
    let value = wrapper_strip_repeated(value);
    MARKERS
        .iter()
        .any(|candidate| label.eq_ignore_ascii_case(candidate))
        && value.len() == 40
        && value.bytes().all(|b| b.is_ascii_hexdigit())
}

fn is_exact_hex_revision(value: &str) -> bool {
    value.len() == 40 && value.bytes().all(|byte| byte.is_ascii_hexdigit())
}

/// Repository-native revision coordinates embedded in a URL/HTML token.
///
/// This intentionally recognizes only exact 40-hex revisions after a
/// canonical repository path marker, plus an exact `href=<40hex>` target.
/// Arbitrary query values, prefixes, and credential-length hex elsewhere in
/// markup remain subject to the normal detector.
fn is_repository_revision_reference(raw_token: &str) -> bool {
    let token = wrapper_strip_repeated(raw_token);
    let low = token.to_ascii_lowercase();

    for marker in ["/blob/", "/tree/", "/commit/", "/commits/"] {
        let mut from = 0usize;
        while let Some(relative) = low[from..].find(marker) {
            let value_start = from + relative + marker.len();
            let remainder = &token[value_start..];
            let value_end = remainder
                .bytes()
                .position(|byte| !byte.is_ascii_hexdigit())
                .unwrap_or(remainder.len());
            if is_exact_hex_revision(&remainder[..value_end]) {
                return true;
            }
            from = value_start.min(low.len());
            if from == low.len() {
                break;
            }
        }
    }

    for (prefix, quote) in [("href=\"", '"'), ("href='", '\'')] {
        if let Some(start) = low.find(prefix) {
            let value = &token[start + prefix.len()..];
            if let Some(end) = value.find(quote) {
                if is_exact_hex_revision(&value[..end]) {
                    return true;
                }
            }
        }
    }

    false
}

fn trailing_identifier(text: &str) -> &str {
    let trimmed = text.trim_end_matches(|c: char| !c.is_ascii_alphanumeric() && c != '_');
    trimmed
        .rsplit(|c: char| !c.is_ascii_alphanumeric() && c != '_')
        .next()
        .unwrap_or_default()
}

/// Return whether the identifier immediately preceding a candidate is a
/// credential label. This deliberately does not walk through narrative prose:
/// notation such as `key estimate uses \\operatorname{softmax}` contains a
/// trigger word, but does not assign the LaTeX fragment to that word.
fn has_immediate_credential_label(text: &str, token_offset: usize) -> bool {
    let before = text[..token_offset].trim_end();
    let before = before
        .strip_suffix(':')
        .or_else(|| before.strip_suffix('='))
        .unwrap_or(before);
    let label = trailing_identifier(before).to_ascii_lowercase();

    label == "token"
        || COMPOUND_TRIGGER_WORDS
            .iter()
            .any(|trigger| label.contains(trigger))
        || TRIGGER_WORDS
            .iter()
            .any(|trigger| contains_bounded_word(&label, trigger))
}

/// A repository revision URL/href is exempt from broad trigger proximity,
/// but never from a direct credential label. When a value separator is
/// present immediately before the reference, only its actual field label is
/// authoritative: narrative shapes such as `key-scoped source citation:`
/// must not turn the earlier adjective into the citation value's label.
fn has_direct_repository_credential_label_with_inline(
    text: &str,
    token_offset: usize,
    inline_trigger: bool,
) -> bool {
    if inline_trigger {
        return true;
    }
    let before = text[..token_offset].trim_end();
    if before.ends_with(':') || before.ends_with('=') {
        return has_immediate_credential_label(text, token_offset);
    }
    has_clause_credential_label_with_inline(
        text,
        token_offset,
        false,
        ClauseValueKind::VcsReference,
    )
}

/// Words the clause walk in [`has_clause_credential_label_with_inline`] steps over when
/// searching backwards for a credential label. Connectors are the words that
/// commonly sit between a label and its value in natural assignment prose
/// ("api key value is X", "the token was X"); the VCS coordinate markers are
/// included so the marker itself cannot shield an earlier label from the
/// walk ("api key value is commit <hex>"); prepositions, determiners, and
/// possessives are the glue of noun-compound label qualifiers ("api key for
/// our production deploy: X") and carry no content of their own.
const LABEL_CLAUSE_SKIP_WORDS: &[&str] = &[
    "commit",
    "revision",
    "rev",
    "sha",
    "is",
    "was",
    "are",
    "were",
    "be",
    "been",
    "being",
    "value",
    "values",
    "the",
    "a",
    "an",
    "this",
    "that",
    "it",
    "its",
    "as",
    "here",
    "now",
    "currently",
    "equals",
    "for",
    "of",
    "to",
    "in",
    "on",
    "at",
    "by",
    "with",
    "from",
    "per",
    "and",
    "or",
    "our",
    "my",
    "your",
    "their",
];

/// Maximum identifiers the clause walk examines. Bounds the scan cost to one
/// short assignment clause. Exhausting the budget is NOT evidence of absence:
/// when a value delimiter was crossed, running out of steps fails CLOSED
/// (treated as credential-labeled) — a truncated scan cannot prove the clause
/// is unlabeled, and any exhaustion-fails-open rule re-admits the labeled
/// value bypass one natural word past the budget. Sized so a label separated
/// from its value by connectors plus a dotted version qualifier ("api key
/// v1.2 value is commit <hex>" — the version costs two identifier steps)
/// stays in range without exhaustion.
const LABEL_CLAUSE_WALK_LIMIT: usize = 8;

/// File-path candidates may walk across at most this many content identifiers
/// without a `:`/`=` delimiter. Two reaches the direct-label shapes that need
/// protection (`auth scanner found <path>`) while keeping the walk local.
const FILE_PATH_NO_DELIMITER_CONTENT_LIMIT: usize = 2;

/// The two narrow trigger-context exemptions need different no-delimiter
/// behavior. VCS coordinates preserve the strict prose guard that keeps
/// `the key changes are in commit <sha>` readable; file paths admit the
/// bounded bridge above so a short label cannot disguise a credential value.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ClauseValueKind {
    VcsReference,
    FilePath,
}

/// End offset of a sentence/paragraph boundary beginning at `index`.
///
/// A single newline remains intra-sentence so natural credential assignments
/// such as `api key:\n<value>` stay protected. Blank lines, clause-ending
/// punctuation, and a period followed by a non-alphanumeric byte end the
/// surrounding trigger context. The period rule deliberately keeps `v1.2`
/// intra-sentence.
fn sentence_boundary_end_at(bytes: &[u8], index: usize) -> Option<usize> {
    match bytes.get(index).copied()? {
        b';' | b'!' | b'?' => Some(index + 1),
        b'.' if bytes
            .get(index + 1)
            .is_some_and(|next| !next.is_ascii_alphanumeric()) =>
        {
            Some(index + 1)
        }
        b'\n' if bytes.get(index + 1) == Some(&b'\n') => Some(index + 2),
        b'\r'
            if bytes
                .get(index..index + 4)
                .is_some_and(|window| window == b"\r\n\r\n") =>
        {
            Some(index + 4)
        }
        _ => None,
    }
}

/// Context after the final sentence boundary in `text`.
fn after_last_sentence_boundary(text: &str) -> &str {
    let bytes = text.as_bytes();
    let mut start = 0usize;
    for index in 0..bytes.len() {
        if let Some(end) = sentence_boundary_end_at(bytes, index) {
            start = end;
        }
    }
    &text[start..]
}

/// Context before the first sentence boundary in `text`.
fn before_first_sentence_boundary(text: &str) -> &str {
    let bytes = text.as_bytes();
    for index in 0..bytes.len() {
        if sentence_boundary_end_at(bytes, index).is_some() {
            return &text[..index];
        }
    }
    text
}

/// Sentence/paragraph boundary inside a clause-walk gap. `;`, `!`, `?`, and
/// blank lines always end the clause. `.` ends it only when it is not
/// immediately followed by an alphanumeric character: a dot tight between
/// identifier fragments ("v1.2") is intra-token punctuation, while a dot at
/// the end of the gap abuts the next identifier (gaps end where the adjacent
/// identifier begins) and is likewise intra-token.
fn gap_has_sentence_boundary(gap: &str) -> bool {
    let bytes = gap.as_bytes();
    (0..bytes.len()).any(|index| sentence_boundary_end_at(bytes, index).is_some())
}

/// Version-shaped identifier fragment ("2", "v1", "12") — the pieces a dotted
/// version qualifier like `v1.2` splits into under identifier extraction.
/// Treated as connector material so a versioned label ("api key v1.2 value
/// is …") stays reachable.
fn is_version_fragment(word: &str) -> bool {
    let digits = word
        .strip_prefix('v')
        .or_else(|| word.strip_prefix('V'))
        .unwrap_or(word);
    !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit())
}

/// Hex-run identifier long enough to be credential material rather than a
/// word ("0123456789abcdef01234567"). Treated as connector material by the
/// clause walk: a separator-split payload fragment sitting between the
/// candidate value and its label is value material, not a label word that
/// ends the clause.
fn is_hex_fragment_word(word: &str) -> bool {
    word.len() >= 12 && word.bytes().all(|b| b.is_ascii_hexdigit())
}

/// Allocation-free case-insensitive substring search for ASCII identifiers.
fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
    haystack
        .as_bytes()
        .windows(needle.len())
        .any(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
}

/// A trailing identifier can contain only ASCII alphanumerics and `_`, so
/// splitting on `_` exactly preserves the bare-trigger boundary rule used by
/// [`contains_bounded_word`] without allocating a lowercase copy.
fn clause_label_has_credential_trigger(label: &str) -> bool {
    label.eq_ignore_ascii_case("token")
        || COMPOUND_TRIGGER_WORDS
            .iter()
            .any(|trigger| contains_ascii_case_insensitive(label, trigger))
        || label.split('_').any(|part| {
            TRIGGER_WORDS
                .iter()
                .any(|trigger| part.eq_ignore_ascii_case(trigger))
        })
}

fn is_label_clause_skip_word(label: &str) -> bool {
    LABEL_CLAUSE_SKIP_WORDS
        .iter()
        .any(|word| label.eq_ignore_ascii_case(word))
}

/// Words ending in the byte sequence `ed` are only a cheap proxy for a
/// regular English participle. Keep known lexical false matches explicit so
/// a noun such as `hundred` cannot become evidence that a credential label is
/// merely narrative prose. Irregular forms such as `found` deliberately do
/// not qualify: they must not shield `api key found <value>`.
fn is_clause_narrative_participle(label: &str) -> bool {
    const NON_PARTICIPLE_ED_WORDS: &[&str] = &["hundred"];

    label.len() >= 5
        && label
            .get(label.len().saturating_sub(2)..)
            .is_some_and(|suffix| suffix.eq_ignore_ascii_case("ed"))
        && !NON_PARTICIPLE_ED_WORDS
            .iter()
            .any(|word| label.eq_ignore_ascii_case(word))
}

/// Cheap regular-gerund proxy used only after the no-delimiter file-path walk
/// has crossed an explicit `in` on the value side (`api_key handling in
/// <path>`). Adjacency alone is never narrative evidence: `api key handling
/// <value>` must keep walking to the direct credential label.
fn is_clause_narrative_gerund(label: &str) -> bool {
    label.len() >= 6
        && label
            .get(label.len().saturating_sub(3)..)
            .is_some_and(|suffix| suffix.eq_ignore_ascii_case("ing"))
}

/// `true` when the candidate token sits in credential-value syntax: an inline
/// credential shape on the token itself, or a credential label reachable by
/// walking backwards through the current clause. The walk steps over
/// [`LABEL_CLAUSE_SKIP_WORDS`], version fragments, and long hex fragments,
/// and stops at a sentence/paragraph boundary (see
/// [`gap_has_sentence_boundary`]) — a label on the far side of a boundary is
/// prose context, not this value's label. Crossing a value delimiter (`:` or
/// `=`, including one attached to a VCS marker: "deploy sha: <hex>" is still
/// assignment syntax) additionally lets the walk step over content words
/// outside those sets, bounded only by [`LABEL_CLAUSE_WALK_LIMIT`], the
/// sentence boundary, and the past-participle stop: "label with qualifiers:
/// value" names the value regardless of how many qualifier nouns the label
/// carries ("api key for production deploy: X", "api key for shared
/// encrypted deploy: X"). A per-clause content-word cap was tried here and
/// removed — any cap re-admits the labeled-value bypass one natural
/// qualifier past the cap. For the same reason, exhausting the walk budget
/// after crossing a delimiter fails CLOSED: the clause is assignment-shaped
/// and its head was never scanned, so it is treated as credential-labeled.
/// A regular past-participle content word ("flagged", "introduced") ends the walk —
/// verb-phrase prose narrates an action on the value rather than labeling it
/// ("the auth scanner flagged this file: <path>", "one extra token was
/// introduced by sha: <hex>"). Coordinating conjunctions are transparent to
/// that position test — "shared and encrypted deploy" keeps both participles
/// in adjective position. Without a delimiter, VCS references step over only
/// the closed connector sets, preserving ordinary prose such as "the key
/// changes are in commit <hex>". File paths additionally step over at most
/// [`FILE_PATH_NO_DELIMITER_CONTENT_LIMIT`] content words, closing direct
/// label shapes such as "auth scanner found <path>" without broadening the
/// VCS tier.
fn has_clause_credential_label_with_inline(
    text: &str,
    token_offset: usize,
    inline_trigger: bool,
    value_kind: ClauseValueKind,
) -> bool {
    if inline_trigger {
        return true;
    }

    let mut rest = &text[..token_offset];
    let mut crossed_value_delimiter = false;
    let mut no_delimiter_content_words = 0usize;
    // Whether the previously processed identifier (the one nearer the value)
    // was the literal preposition `in`. This starts false deliberately:
    // adjacency to the value must not make a gerund narrative evidence.
    let mut arrived_through_in_preposition = false;
    // Whether the previously processed identifier (the one nearer the value)
    // was connector material. Starts true: step 0 is adjacent to the value or
    // its delimiter.
    let mut arrived_through_connector = true;
    for step in 0..LABEL_CLAUSE_WALK_LIMIT {
        let label = trailing_identifier(rest);
        if label.is_empty() {
            return false;
        }
        let gap = &rest[label.as_ptr() as usize - rest.as_ptr() as usize + label.len()..];
        if step > 0 && gap_has_sentence_boundary(gap) {
            return false;
        }
        if gap.contains([':', '=']) {
            crossed_value_delimiter = true;
        }
        if clause_label_has_credential_trigger(label) {
            return true;
        }
        let skippable = is_label_clause_skip_word(label)
            || is_version_fragment(label)
            || is_hex_fragment_word(label);
        if !skippable {
            // This barrier applies to delimiter-bearing clauses and to the
            // bounded file-path bridge. It intentionally recognizes regular
            // `-ed` forms only: `found` is a bridge word, not a narrative
            // shield for a direct credential label.
            let no_delimiter_file_path_narrative = !crossed_value_delimiter
                && value_kind == ClauseValueKind::FilePath
                && arrived_through_in_preposition
                && is_clause_narrative_gerund(label);
            // Delimiter-bearing clauses and VCS coordinates preserve their
            // existing direct-participle semantics. A no-delimiter file path
            // must first process real value-side context: the synthetic
            // initial connector state alone cannot let `api key leaked
            // <value>` stop before reaching the trigger.
            let regular_participle_narrative = is_clause_narrative_participle(label)
                && (crossed_value_delimiter || value_kind != ClauseValueKind::FilePath || step > 0);
            if arrived_through_connector
                && (regular_participle_narrative || no_delimiter_file_path_narrative)
            {
                return false;
            }
            if !crossed_value_delimiter {
                if value_kind != ClauseValueKind::FilePath
                    || no_delimiter_content_words >= FILE_PATH_NO_DELIMITER_CONTENT_LIMIT
                {
                    return false;
                }
                no_delimiter_content_words += 1;
            }
        }
        // Coordinating conjunctions are transparent to participle-position
        // classification: in "shared and encrypted deploy" the coordination
        // as a whole is followed by a content noun, so "shared" is still an
        // adjective — the conjunction preserves the arrived state instead of
        // marking connector position.
        if !label.eq_ignore_ascii_case("and") && !label.eq_ignore_ascii_case("or") {
            arrived_through_connector = skippable;
        }
        arrived_through_in_preposition = label.eq_ignore_ascii_case("in");
        let start = label.as_ptr() as usize - rest.as_ptr() as usize;
        rest = &rest[..start];
    }
    // Budget exhausted. A clause that crossed a value delimiter and ran out
    // of steps without a sentence boundary or verb-position participle is
    // assignment-shaped with an unscanned head — fail closed rather than let
    // clause length launder a labeled credential into the exemptions.
    crossed_value_delimiter
}

fn is_plausible_file_path(token: &str) -> bool {
    let token = token.trim_start_matches(|c: char| {
        matches!(
            c,
            '"' | '\'' | '`' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ';'
        )
    });
    let token = token.trim_end_matches(|c: char| {
        matches!(
            c,
            '"' | '\'' | '`' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ';' | '.'
        )
    });
    let path = if let Some(angle_path) = token.strip_prefix('<') {
        let Some(close) = angle_path.rfind('>') else {
            return false;
        };
        if !is_line_location_suffix(&angle_path[close + 1..]) {
            return false;
        }
        &angle_path[..close]
    } else if let Some((path, suffix)) = token.rsplit_once(':') {
        if is_line_location_suffix(suffix) {
            path
        } else {
            token
        }
    } else {
        token
    };

    if path.contains("://")
        || !path.contains('/')
        || !path
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'/' | b'.' | b'_' | b'-' | b'~'))
    {
        return false;
    }

    let segment_count = path
        .split('/')
        .filter(|segment| !segment.is_empty())
        .count();
    segment_count >= 2 || (path.starts_with('/') && segment_count == 1)
}

/// Narrow high-entropy exemption for mathematical notation (#1988).
///
/// A fragment needs both a LaTeX control sequence and several structural
/// delimiters. Any embedded credential-length hex or independently
/// high-entropy alphanumeric run disables the exemption, so wrapping an
/// opaque value in `\texttt{...}` does not launder it.
fn is_latex_fragment_without_credential_run(token: &str) -> bool {
    let bytes = token.as_bytes();
    let has_control_sequence = bytes
        .windows(2)
        .any(|pair| pair[0] == b'\\' && pair[1].is_ascii_alphabetic());
    let structural_count = bytes
        .iter()
        .filter(|byte| matches!(byte, b'\\' | b'{' | b'}' | b'^' | b'_'))
        .count();
    if !has_control_sequence || structural_count < 3 {
        return false;
    }

    if normalized_hex_credential_span(token).is_some() {
        return false;
    }

    !token
        .split(|ch: char| !ch.is_ascii_alphanumeric())
        .filter(|run| run.len() >= MIN_ENTROPY_LEN)
        .any(|run| shannon_entropy(run.as_bytes()) >= ENTROPY_THRESHOLD)
}

/// A SHA-256 value is admitted only with a nearby checksum designation, not
/// with a credential field that merely happens to describe its encoding.
fn is_labeled_sha256_digest(text: &str, token_offset: usize, token: &str) -> bool {
    if token.len() != 64 || !token.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        return false;
    }
    let before = text[..token_offset]
        .trim_end_matches(|ch: char| ch.is_ascii_whitespace() || matches!(ch, ':' | '='));
    let marker = ["sha256 key digest", "sha256 digest", "sha256"]
        .into_iter()
        .find(|marker| {
            before
                .get(before.len().saturating_sub(marker.len())..)
                .is_some_and(|tail| tail.eq_ignore_ascii_case(marker))
        });
    let Some(marker) = marker else {
        return false;
    };
    let marker_start = before.len() - marker.len();
    if marker_start > 0
        && text[..marker_start]
            .chars()
            .next_back()
            .is_some_and(|ch| ch.is_ascii_alphanumeric() || ch == '_')
    {
        return false;
    }
    !has_clause_credential_label_with_inline(text, marker_start, false, ClauseValueKind::FilePath)
}

/// Inline Rust call references have syntax that an opaque credential does not:
/// backticks, a qualified symbol, and an empty argument list. Arguments are
/// excluded because their values would otherwise become part of the exemption.
fn is_prose_code_reference(member: &str, token: &str) -> bool {
    let Some(code) = member.strip_prefix('`').and_then(|s| s.strip_suffix('`')) else {
        return false;
    };
    if code != token || !code.ends_with("()") {
        return false;
    }
    let Some((owner, method)) = code[..code.len() - 2].split_once("::") else {
        return false;
    };
    owner
        .as_bytes()
        .first()
        .is_some_and(|b| b.is_ascii_alphabetic())
        && owner
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'_')
        && method
            .as_bytes()
            .first()
            .is_some_and(|b| b.is_ascii_alphabetic())
        && method
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b':' | b'<' | b'>'))
        && !method.contains("::")
}

/// Uppercase environment references are names, not values, when their final
/// component names a conventional non-secret field. The run checks above
/// still refuse any credential-shaped component inside the name.
fn is_environment_name(token: &str) -> bool {
    let mut components = token.split('_');
    let Some(first) = components.next() else {
        return false;
    };
    if first.is_empty() || !first.bytes().all(|b| b.is_ascii_uppercase()) {
        return false;
    }
    let mut count = 0;
    let mut last = "";
    for part in components {
        if part.is_empty()
            || part.len() > 16
            || !part
                .bytes()
                .all(|b| b.is_ascii_uppercase() || b.is_ascii_digit())
        {
            return false;
        }
        count += 1;
        last = part;
    }
    count >= 3 && matches!(last, "PATH" | "FILE" | "NAME" | "TTL")
}

/// Closed, familiar math commands keep this exemption on notation rather
/// than arbitrary backslash-prefixed strings.
fn is_latex_prose_macro(token: &str) -> bool {
    [
        "\\mathsf{",
        "\\mathbf{",
        "\\mathcal{",
        "\\mathrm{",
        "\\operatorname{",
    ]
    .iter()
    .any(|prefix| token.starts_with(prefix))
        && is_latex_fragment_without_credential_run(token)
}

/// Recognize two unambiguous AWS resource address forms. The resource path
/// is restricted to short name segments; an embedded long credential run is
/// refused before this predicate is reached.
fn is_aws_resource_name(token: &str) -> bool {
    let mut parts = token.splitn(6, ':');
    let (Some("arn"), Some("aws"), Some(service), Some(region), Some(account), Some(resource)) = (
        parts.next(),
        parts.next(),
        parts.next(),
        parts.next(),
        parts.next(),
        parts.next(),
    ) else {
        return false;
    };
    let valid_resource = !resource.is_empty()
        && resource.split('/').all(|segment| {
            !segment.is_empty()
                && segment.len() <= 24
                && segment
                    .bytes()
                    .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
        });
    valid_resource
        && ((service == "s3" && region.is_empty() && account.is_empty())
            || (service == "iam"
                && region.is_empty()
                && account.len() == 12
                && account.bytes().all(|b| b.is_ascii_digit())
                && (resource.starts_with("role/") || resource.starts_with("policy/"))))
}

fn is_line_location_suffix(suffix: &str) -> bool {
    if suffix.is_empty() {
        return true;
    }
    let suffix = suffix.strip_prefix(':').unwrap_or(suffix);
    let suffix = suffix.strip_prefix('~').unwrap_or(suffix);
    let mut parts = suffix.split('-');
    let Some(start) = parts.next() else {
        return false;
    };
    !start.is_empty()
        && start.bytes().all(|b| b.is_ascii_digit())
        && parts
            .next()
            .is_none_or(|end| !end.is_empty() && end.bytes().all(|b| b.is_ascii_digit()))
        && parts.next().is_none()
}

/// The raw span whose consecutive pure-hex runs — splitting on every
/// non-alphanumeric character and dropping the separators for length
/// accounting — reach one of [`HEX_CREDENTIAL_LENGTHS`].
///
/// Closes the separator-dilution bypass (#1062) where a credential-length
/// hex payload is spread across multiple runs each individually below
/// [`MIN_ENTROPY_LEN`]: `0123456789abcdef0123/456789abcdef01234567` is two
/// 20-char hex runs that never individually reach 24 chars or a
/// credential-length boundary, but normalize to one 40-char hex sequence.
/// A non-hex, non-empty run resets the running sum — this only bridges
/// ADJACENT hex runs, not hex fragments scattered across unrelated filler.
fn normalized_hex_credential_span(token: &str) -> Option<&str> {
    let mut concatenated_len = 0usize;
    let mut span_start = 0usize;
    for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
        if run.is_empty() {
            continue;
        }
        if is_hex_run(run) {
            let run_start = run.as_ptr() as usize - token.as_ptr() as usize;
            if concatenated_len == 0 {
                span_start = run_start;
            }
            concatenated_len += run.len();
            if HEX_CREDENTIAL_LENGTHS.contains(&concatenated_len) {
                return Some(&token[span_start..run_start + run.len()]);
            }
        } else {
            concatenated_len = 0;
        }
    }
    None
}

/// `true` when the gap `text[gap_start..gap_end]` between two adjacent
/// tokenizer tokens holds no ASCII alphanumeric character — the shape a
/// tokenizer-delimiting separator (ASCII whitespace, or a non-ASCII
/// character such as U+200B; see the tokenizer comment in
/// [`check_entropy_heuristic`]) leaves behind when it splits one credential
/// payload into two tokens. Deliberately UNBOUNDED on gap byte length
/// (#1062: a byte-length bound here is defeated outright by
/// repeating the delimiter character) — [`bridge_fragment_chain`] is what
/// keeps the overall reconstruction bounded, via [`MAX_BRIDGE_FRAGMENTS`],
/// not this check. This still never bridges tokens separated by a genuine
/// word or sentence: any real word in the gap contains an ASCII alphanumeric
/// character and fails the check immediately.
fn adjacent_gap_is_bridgeable(text: &str, gap_start: usize, gap_end: usize) -> bool {
    gap_end >= gap_start && !text[gap_start..gap_end].contains(|c: char| c.is_ascii_alphanumeric())
}

/// `true` when `s` is shaped like a plausible FRAGMENT of a separator-split
/// credential: alphanumeric-only and at least [`MIN_BRIDGE_FRAGMENT_LEN`]
/// bytes. Shared by the short-token anchor-admission check in
/// [`check_entropy_heuristic`] and by [`bridge_fragment_chain`]'s outward
/// walk. A long anchor can reach reconstruction without satisfying this
/// shape, but every neighboring fragment merged into its chain must satisfy
/// it. This stops the walk at a short trigger/glue word (`key`, `api`, `for`)
/// sitting immediately beside the real fragments (#1062).
fn is_bridge_fragment_shape(s: &str) -> bool {
    s.len() >= MIN_BRIDGE_FRAGMENT_LEN && s.bytes().all(|b| b.is_ascii_alphanumeric())
}

/// `true` when `s` holds no ASCII alphanumeric character at all — the same
/// predicate [`adjacent_gap_is_bridgeable`] applies to the byte-range GAP
/// between two tokenizer tokens, applied here to a tokenizer TOKEN itself
/// (`s` is always non-empty: the tokenizer filters empty tokens). A
/// delimiter-only token such as `---` sitting between two Unicode-separator
/// gaps (#1062) carries none of a credential's own
/// characters — it is exactly as transparent to reconstruction as the
/// surrounding whitespace/Unicode gaps are, so [`bridge_fragment_chain`]
/// treats it as glue to walk across, not as a chain-terminating non-fragment
/// token. A token can never be both this and [`is_bridge_fragment_shape`]:
/// the latter requires only alphanumeric bytes, this requires none.
fn is_delimiter_only_token(s: &str) -> bool {
    !s.bytes().any(|b| b.is_ascii_alphanumeric())
}

/// Looks outward from `tokens[edge]` in `dir` (`-1` = toward index 0, `+1` =
/// toward the end) for the next [`is_bridge_fragment_shape`] token, walking
/// transparently across up to [`MAX_BRIDGE_GLUE_TOKENS`] consecutive
/// [`is_delimiter_only_token`] glue tokens along the way. Every gap crossed
/// — including the ones on either side of a glue token — must be
/// [`adjacent_gap_is_bridgeable`]. Returns the found fragment's index, or
/// `None` if the walk runs off the end of `tokens`, meets a token that is
/// neither a fragment nor glue, meets a non-bridgeable gap, or exhausts the
/// glue budget before finding a fragment.
fn probe_bridge_fragment(
    tokens: &[(usize, &str)],
    text: &str,
    edge: usize,
    dir: isize,
) -> Option<usize> {
    let mut i = edge;
    let mut glue_skipped = 0usize;
    loop {
        let next_i = i.checked_add_signed(dir)?;
        if next_i >= tokens.len() {
            return None;
        }
        let (lo, hi) = if dir < 0 { (next_i, i) } else { (i, next_i) };
        let (lo_offset, lo_raw) = tokens[lo];
        let (hi_offset, _) = tokens[hi];
        let gap_start = lo_offset + lo_raw.len();
        if !adjacent_gap_is_bridgeable(text, gap_start, hi_offset) {
            return None;
        }
        let candidate = strip_delimiters(tokens[next_i].1);
        if is_bridge_fragment_shape(candidate) {
            return Some(next_i);
        }
        if is_delimiter_only_token(candidate) && glue_skipped < MAX_BRIDGE_GLUE_TOKENS {
            glue_skipped += 1;
            i = next_i;
            continue;
        }
        return None;
    }
}

/// Reconstructs the bounded chain of tokenizer fragments containing
/// `tokens[anchor_idx]`, by walking outward in both directions via
/// [`probe_bridge_fragment`] until the chain has reached
/// [`MAX_BRIDGE_FRAGMENTS`] real fragments or neither direction can extend
/// further. Returns each REAL fragment's [`strip_delimiters`]-ed body, in
/// document order, for the caller to recombine — any delimiter-only glue
/// tokens absorbed along the way (#1062) are dropped from the
/// result entirely, so a caller joining fragments with a space
/// ([`normalized_hex_credential_span`]) or concatenating them directly
/// (the generic entropy check) sees only the genuine fragments, exactly as
/// if the glue were more gap. Extends both directions every iteration so a
/// credential split with fragments on both sides of the anchor (e.g. the
/// anchor is the MIDDLE fragment of a three-way split) is fully
/// reconstructed, not just one side of it. A length-1 result means no
/// extension was possible — callers should skip further work in that case.
/// The anchor itself is included without a fragment-shape check; only outward
/// extensions are admitted through [`probe_bridge_fragment`].
fn bridge_fragment_chain<'a>(
    tokens: &[(usize, &'a str)],
    text: &str,
    anchor_idx: usize,
) -> Vec<&'a str> {
    let mut start = anchor_idx;
    let mut end = anchor_idx;
    let mut fragment_count = 1usize;

    loop {
        let mut extended = false;
        if fragment_count < MAX_BRIDGE_FRAGMENTS && start > 0 {
            if let Some(new_start) = probe_bridge_fragment(tokens, text, start, -1) {
                start = new_start;
                fragment_count += 1;
                extended = true;
            }
        }
        if fragment_count < MAX_BRIDGE_FRAGMENTS && end + 1 < tokens.len() {
            if let Some(new_end) = probe_bridge_fragment(tokens, text, end, 1) {
                end = new_end;
                fragment_count += 1;
                extended = true;
            }
        }
        if !extended {
            break;
        }
    }

    tokens[start..=end]
        .iter()
        .map(|&(_, raw)| strip_delimiters(raw))
        .filter(|stripped| !is_delimiter_only_token(stripped))
        .collect()
}

/// Extra backward truncation [`mask_bounded`] applies after it drops the
/// token straddling the window boundary.
///
/// `bridge_fragment_chain` can reconstruct a credential from up to
/// [`MAX_BRIDGE_FRAGMENTS`] whitespace-separated pieces, each individually
/// too short or low-entropy on its own to be recognized. The gap between two
/// fragments is deliberately unbounded in byte length
/// (`adjacent_gap_is_bridgeable`), so there is no finite forward lookahead
/// past the window boundary that could guarantee seeing every fragment of a
/// chain straddling the cut — a chain can be padded arbitrarily far past the
/// window by a single long glue token, which still counts as only one hop
/// against [`MAX_BRIDGE_GLUE_TOKENS`]. Rather than scan past the boundary,
/// this walks BACKWARD from it — data already read into the window, so the
/// extra work stays bounded by `window_chars` alone and needs no lookahead —
/// dropping every further bridge-fragment-shaped token chained to the
/// fragment [`mask_bounded`] already removed, spending the same
/// fragment-count and glue-token budgets [`bridge_fragment_chain`] would
/// spend walking outward from an anchor.
///
/// Runs unconditionally on every truncated window, regardless of whether the
/// window itself carries trigger-word context. `collect_mask_spans` step 6
/// admits trigger context from EITHER side of a fragment chain (a credential
/// like `<frag> <frag> <frag> is the api key for ...` is reconstructed by the
/// unbounded masker even though the trigger sits after the fragments), so a
/// trigger word that would justify keeping this window's tail may sit past
/// the window boundary — data this function, by construction, cannot see.
/// Gating the walk on an in-window trigger check would leave exactly that
/// case unprotected: the window carries no visible trigger, the walk would
/// never run, and any whole fragments already read into the window would
/// leak. The walk cannot distinguish a genuine chained fragment from an
/// unrelated fragment-shaped word sitting at the tail of an untriggered
/// window either; the trade this makes is dropping that word too rather than
/// risking a leaked credential fragment. The cost is bounded: at most
/// `MAX_BRIDGE_FRAGMENTS - 1` tokens of a tail that mask_bounded has already
/// decided to truncate.
///
/// Returns the byte offset to truncate `window` to, or `None` when nothing
/// beyond the already-trimmed token needs to go.
fn trailing_bridge_fragment_cut(window: &str) -> Option<usize> {
    let tokens = tokenize_entropy_tokens(window);
    let mut idx = tokens.len().checked_sub(1)?;
    let mut fragment_budget = MAX_BRIDGE_FRAGMENTS - 1;
    let mut glue_budget = MAX_BRIDGE_GLUE_TOKENS;
    let mut cut_at = None;

    loop {
        let (offset, raw) = tokens[idx];
        let candidate = strip_delimiters(raw);
        if is_bridge_fragment_shape(candidate) {
            if fragment_budget == 0 {
                break;
            }
            fragment_budget -= 1;
            glue_budget = MAX_BRIDGE_GLUE_TOKENS;
            cut_at = Some(offset);
        } else if is_delimiter_only_token(candidate) {
            if glue_budget == 0 {
                break;
            }
            glue_budget -= 1;
        } else {
            break;
        }

        if idx == 0 {
            break;
        }
        let (prev_offset, prev_raw) = tokens[idx - 1];
        let gap_start = prev_offset + prev_raw.len();
        if !adjacent_gap_is_bridgeable(window, gap_start, offset) {
            break;
        }
        idx -= 1;
    }

    cut_at
}

/// Returns `true` when `low_window` contains `needle` as a standalone word —
/// bounded on both sides by a character outside the word-char set (or
/// start/end of string) — rather than merely as a substring.
/// `underscore_is_word_char` selects the boundary rule the caller needs; see
/// `docs/api/secret_gate.md#contains_word` for the two deliberately different
/// rules and why each caller needs its own.
fn contains_word(low_window: &str, needle: &str, underscore_is_word_char: bool) -> bool {
    let is_word_char = |c: char| c.is_ascii_alphanumeric() || (underscore_is_word_char && c == '_');
    let mut start = 0;
    while let Some(rel) = low_window[start..].find(needle) {
        let abs = start + rel;
        let before_ok = abs == 0
            || low_window[..abs]
                .chars()
                .next_back()
                .is_none_or(|c| !is_word_char(c));
        let after_end = abs + needle.len();
        let after_ok = after_end >= low_window.len()
            || low_window[after_end..]
                .chars()
                .next()
                .is_none_or(|c| !is_word_char(c));
        if before_ok && after_ok {
            return true;
        }
        start = abs + needle.len().max(1);
    }
    false
}

/// Returns `true` when `low_window` contains the bare trigger word `needle`
/// as a standalone word, with underscore treated as a BOUNDARY (see
/// [`contains_word`]) — so `secret_key=…`/`auth_token=…`/`signing_key=…`
/// still match (on the `secret`/`auth`/`key` half), while pure letter-joined
/// collisions like `authorized`/`authentication`/`monkey`/`keyword` do not.
fn contains_bounded_word(low_window: &str, needle: &str) -> bool {
    if needle != "key" {
        return contains_word(low_window, needle, false);
    }
    low_window
        .split(|c: char| !c.is_ascii_alphanumeric() && c != '_')
        .any(|label| {
            if !contains_word(label, needle, false) {
                return false;
            }
            let end = label.as_ptr() as usize - low_window.as_ptr() as usize + label.len();
            let after = low_window[end..].trim_start_matches(is_assignment_label_gap);
            !(is_lookup_key_label(label) && after.starts_with([':', '=']))
        })
}

fn is_assignment_label_gap(c: char) -> bool {
    matches!(c, '"' | '\'' | '`')
}

/// Closed vocabulary of member names whose `_key` suffix names a lookup
/// identifier rather than a credential (issue #2654). The exception is an
/// allowlist on purpose: any other `*_key` label keeps `key` as a credential
/// trigger, so unknown compounds such as `hmac_key`, `master_key`, `ssh_key`,
/// `jwt_key`, `webhook_key` or `license_key` stay refused. The match is the
/// whole label: a qualified spelling such as `left_association_key` or
/// `hmac_cache_key` is not in the vocabulary and keeps its trigger, because a
/// prefix rule would re-open every compound the list closes (`hmac_` is not a
/// trigger word, so `hmac_cache_key` would strip to a listed suffix).
const LOOKUP_KEY_LABELS: &[&str] = &[
    "association_key",
    "cache_key",
    "composite_key",
    "dedup_key",
    "foreign_key",
    "idempotency_key",
    "index_key",
    "lookup_key",
    "map_key",
    "natural_key",
    "partition_key",
    "primary_key",
    "range_key",
    "routing_key",
    "row_key",
    "search_key",
    "shard_key",
    "sort_key",
    "surrogate_key",
    "unique_key",
];

fn is_lookup_key_label(label: &str) -> bool {
    LOOKUP_KEY_LABELS.contains(&label)
}

/// Finds a canonical compound credential label beginning at an identifier
/// boundary. The trailing edge is deliberately unbounded so version suffixes
/// and larger underscore-composed labels remain protected.
fn compound_trigger(low_text: &str) -> Option<&'static str> {
    COMPOUND_TRIGGER_WORDS.iter().copied().find(|needle| {
        let mut start = 0;
        while let Some(rel) = low_text[start..].find(needle) {
            let abs = start + rel;
            let before_ok = abs == 0
                || low_text[..abs]
                    .chars()
                    .next_back()
                    .is_none_or(|c| !c.is_ascii_alphanumeric());
            if before_ok {
                return true;
            }
            start = abs + needle.len();
        }
        false
    })
}

fn find_trigger(text: &str, credential_label_only: bool) -> Option<&'static str> {
    let low = text.to_ascii_lowercase();
    TRIGGER_WORDS
        .iter()
        .copied()
        .find(|tw| contains_bounded_word(&low, tw))
        .or_else(|| compound_trigger(&low))
        .or_else(|| {
            ((!credential_label_only && has_standalone_token(&low)) || has_token_assignment(&low))
                .then_some("token")
        })
        .or_else(|| assignment_credential_trigger(&low))
}

/// Detect a credential-bearing assignment label before an `=` or `:`.
///
/// The separator may be preceded by whitespace or a JSON quote. Compound
/// triggers deliberately retain substring matching inside the label so common
/// version suffixes such as `api_keyv2` remain protected.
fn assignment_credential_trigger(low_text: &str) -> Option<&'static str> {
    low_text.char_indices().find_map(|(index, ch)| {
        if !matches!(ch, '=' | ':') {
            return None;
        }
        let before =
            low_text[..index].trim_end_matches(|c: char| !c.is_ascii_alphanumeric() && c != '_');
        let label = before
            .rsplit(|c: char| !c.is_ascii_alphanumeric() && c != '_')
            .next()
            .unwrap_or_default();
        COMPOUND_TRIGGER_WORDS
            .iter()
            .copied()
            .find(|needle| label.contains(needle))
            .or_else(|| {
                TRIGGER_WORDS.iter().copied().find(|tw| {
                    (*tw != "key"
                        || !is_lookup_key_label(label)
                        || !low_text[before.len()..index]
                            .chars()
                            .all(is_assignment_label_gap))
                        && contains_bounded_word(label, tw)
                })
            })
            .or_else(|| (label == "token").then_some("token"))
    })
}

/// Detect credential labels embedded in the same whitespace token as a value.
///
/// The surrounding-context scan deliberately excludes the candidate token so
/// a trigger word inside a path cannot make that path self-trigger. Credential
/// assignments still need to fire when no whitespace separates label and
/// value, including JSON-like forms. Underscore-delimited config identifiers
/// without an assignment are retained for compatibility with shapes such as
/// `session_secret_<value>`.
fn inline_credential_trigger(raw_token: &str) -> Option<&'static str> {
    let low = raw_token.to_ascii_lowercase();
    assignment_credential_trigger(&low).or_else(|| {
        if !low.contains(['/', '-', '.']) && low.contains('_') {
            COMPOUND_TRIGGER_WORDS
                .iter()
                .copied()
                .find(|needle| low.contains(needle))
                .or_else(|| {
                    TRIGGER_WORDS
                        .iter()
                        .copied()
                        .find(|tw| contains_bounded_word(&low, tw))
                })
        } else {
            None
        }
    })
}

/// Returns `true` when `low_window` contains the word `token` as a standalone
/// word, with underscore treated as a WORD CHARACTER / continuation (see
/// [`contains_word`]) — but NOT as part of compound identifiers such as
/// `tokenizer`, `token_count`, or `next_token`. This underscore-as-
/// continuation rule is deliberately different from
/// [`contains_bounded_word`]: `token` alone is not a
/// credential trigger (it fires on too many benign technical terms), so it
/// needs the narrower, underscore-inclusive standalone-word definition,
/// whereas the bare `TRIGGER_WORDS` need underscore-joined compounds like
/// `secret_key` to still register.
fn has_standalone_token(low_window: &str) -> bool {
    contains_word(low_window, "token", true)
}

/// Returns `true` when `low_window` contains the assignment form `token=` or
/// `token:` where the `token` identifier has a word boundary BEFORE it.
///
/// This is boundary-aware so that compound identifiers like `next_token:` or
/// `pagination_token=` do NOT trigger — only a standalone `token=`/`token:`
/// at the start of a field name does.
///
/// Examples that return `true`:  `token=<value>`, `token: <value>`,
///   `"token": "<value>"` (JSON key-value pairs).
/// Examples that return `false`: `next_token: <value>`,
///   `pagination_token=<value>`, `token_count: <value>`.
fn has_token_assignment(low_window: &str) -> bool {
    let needle = "token";
    let mut start = 0;
    while let Some(rel) = low_window[start..].find(needle) {
        let abs = start + rel;
        // Require a word boundary BEFORE `token`.
        let before_ok = abs == 0
            || low_window[..abs]
                .chars()
                .next_back()
                .is_none_or(|c| !c.is_ascii_alphanumeric() && c != '_');
        let after_end = abs + needle.len();
        // Require `=` or `:` immediately after `token` (possibly with surrounding
        // whitespace or quotes stripped by the time we see the lowercased window).
        let after_char = low_window[after_end..].chars().next();
        let after_is_assign = matches!(after_char, Some('=') | Some(':'));
        if before_ok && after_is_assign {
            return true;
        }
        start = abs + needle.len().max(1);
    }
    false
}

// ─── Allowlist helpers ───────────────────────────────────────────────────────

/// Returns `true` for pure-hex tokens (case-insensitive, optional `0x`/`0X` prefix,
/// 8–128 chars) — git SHAs, checksum digests, uuid-hex without hyphens.
///
/// This helper is used with context: pure-hex tokens near credential trigger words
/// are NOT allowlisted (see `check_entropy_heuristic`).  Only call this function
/// when you have already confirmed no trigger context is nearby.
fn is_pure_hex(token: &str) -> bool {
    let hex_part = token
        .strip_prefix("0x")
        .or(token.strip_prefix("0X"))
        .unwrap_or(token);
    hex_part.len() >= 8 && hex_part.len() <= 128 && hex_part.bytes().all(|b| b.is_ascii_hexdigit())
}

/// Returns `true` for tokens that are unambiguous base64/base64url content
/// hashes with an explicit `sha<N>-` prefix (SRI hash, npm lockfile integrity).
/// Bare base64 of the same length WITHOUT the prefix is NOT allowlisted — see
/// `docs/api/secret_gate.md#is_base64_content_hash` for the full criteria list and
/// why the explicit prefix is required.
fn is_base64_content_hash(token: &str) -> bool {
    // Known vendor prefixes — never allowlist even if they look like base64.
    // Includes bare `sk-` to prevent OpenAI-shaped tokens from being allowlisted.
    const VENDOR_PREFIXES: &[&str] = &[
        "sk-",
        "rk_live_",
        "fm2_",
        "vercel_",
        "xoxb-",
        "xoxa-",
        "xoxp-",
        "xoxr-",
        "xoxs-",
        "ghp_",
        "gho_",
        "ghu_",
        "ghs_",
        "ghr_",
        "github_pat_",
        "AKIA",
        "ASIA",
        "AGE-SECRET-KEY-",
        "FlyV1",
    ];
    if VENDOR_PREFIXES.iter().any(|p| token.starts_with(p)) {
        return false;
    }
    // Require an explicit SRI `sha[0-9]+-` prefix.  Bare base64 at sha-length
    // is NOT allowlisted — it is indistinguishable from a real API token.
    let body = if let Some(rest) = token.strip_prefix("sha") {
        // rest starts with digits followed by '-'
        let dash = rest.find('-').unwrap_or(rest.len());
        let digits = &rest[..dash];
        if !digits.is_empty() && digits.bytes().all(|b| b.is_ascii_digit()) && dash < rest.len() {
            &rest[dash + 1..] // everything after "sha<digits>-"
        } else {
            return false; // no valid sha<N>- prefix → not a known content hash
        }
    } else {
        return false; // no sha prefix → not allowlisted
    };
    // Strip optional padding (at most 2 `=`).
    let stripped = body.trim_end_matches('=');
    let pad_removed = body.len() - stripped.len();
    if pad_removed > 2 {
        return false;
    }
    // Accept only SHA-family content-hash lengths (43, 64, 86–88 chars unpadded).
    let n = stripped.len();
    if n != 43 && n != 64 && !(86..=88).contains(&n) {
        return false;
    }
    // Accept both standard-base64 and URL-safe-base64 alphabets.
    stripped
        .bytes()
        .all(|b| b.is_ascii_alphanumeric() || b == b'+' || b == b'/' || b == b'-' || b == b'_')
}

/// Structural separators that gate entry into [`is_structured_identifier`]
/// (rule 1: the token must contain at least one of these). The actual run
/// decomposition (rule 2) splits on every non-alphanumeric character, not
/// just these four — see the doc comment on `is_structured_identifier`.
const STRUCTURAL_SEPARATORS: [char; 4] = ['/', '-', '_', '.'];

/// Largest length a single path/branch/identifier segment (a "run" between
/// separators) may have and still be considered word-shaped.
const MAX_RUN_LEN: usize = 24;

/// Runs whose letter portion is at or below this length skip the
/// case-transition-density check: density is not a meaningful signal on very
/// short runs (e.g. `R1`, `v2`, `ADR`).
const DENSITY_EXEMPT_LETTER_LEN: usize = 4;

/// Maximum case-transition density (transitions divided by letter_count - 1)
/// a run's letter portion may have and still be considered word-shaped.
const MAX_CASE_TRANSITION_DENSITY: f64 = 0.3;

/// Returns `true` when `token` is shaped like a file path, branch name, or
/// other structured identifier rather than a high-entropy secret (word-shaped
/// runs separated by `/`, `-`, `_`, `.`). Exempts from the entropy heuristic
/// ONLY outside trigger context — see the module doc and
/// `docs/api/secret_gate.md#is_structured_identifier` for the run-shape criteria.
fn is_structured_identifier(token: &str) -> bool {
    if !token.contains(|c: char| STRUCTURAL_SEPARATORS.contains(&c)) {
        return false;
    }
    let runs: Vec<&str> = token
        .split(|c: char| !c.is_ascii_alphanumeric())
        .filter(|r| !r.is_empty())
        .collect();
    runs.len() >= 2 && runs.iter().all(|run| is_word_shaped_run(run))
}

/// A single run (segment between structural separators) is word-shaped when
/// it matches `[A-Za-z]+[0-9]*` or `[0-9]+`, is at most [`MAX_RUN_LEN`] chars,
/// and (for the letters-then-digits form) its letter portion has a low
/// case-transition density.
fn is_word_shaped_run(run: &str) -> bool {
    if run.is_empty() || run.len() > MAX_RUN_LEN {
        return false;
    }
    let bytes = run.as_bytes();
    if bytes.iter().all(|b| b.is_ascii_digit()) {
        return true;
    }
    let letter_end = bytes
        .iter()
        .position(|b| !b.is_ascii_alphabetic())
        .unwrap_or(bytes.len());
    // A run that does not start with a letter, and is not pure digits (ruled
    // out above), mixes digits and letters in a shape other than
    // letters-then-digits — not word-shaped.
    if letter_end == 0 {
        return false;
    }
    // Everything after the leading letters must be digits only (no further
    // letters), else the run is not the `[A-Za-z]+[0-9]*` shape.
    if !bytes[letter_end..].iter().all(|b| b.is_ascii_digit()) {
        return false;
    }
    case_transition_density_ok(&run[..letter_end])
}

/// `true` when the case-transition density of `letters` (an all-ASCII-letter
/// string) is at or below [`MAX_CASE_TRANSITION_DENSITY`]. A transition is an
/// adjacent letter pair where one side is uppercase and the other is not.
/// Runs with few enough letters pass automatically (see
/// [`DENSITY_EXEMPT_LETTER_LEN`]) since density is noisy on short strings.
fn case_transition_density_ok(letters: &str) -> bool {
    let chars: Vec<char> = letters.chars().collect();
    if chars.len() <= DENSITY_EXEMPT_LETTER_LEN {
        return true;
    }
    let transitions = chars
        .windows(2)
        .filter(|w| w[0].is_ascii_uppercase() != w[1].is_ascii_uppercase())
        .count();
    let density = transitions as f64 / (chars.len() - 1) as f64;
    density <= MAX_CASE_TRANSITION_DENSITY
}

/// `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
fn is_uuid_canonical(s: &str) -> bool {
    let b = s.as_bytes();
    if b.len() != 36 {
        return false;
    }
    b[8] == b'-'
        && b[13] == b'-'
        && b[18] == b'-'
        && b[23] == b'-'
        && b[..8].iter().all(|c| c.is_ascii_hexdigit())
        && b[9..13].iter().all(|c| c.is_ascii_hexdigit())
        && b[14..18].iter().all(|c| c.is_ascii_hexdigit())
        && b[19..23].iter().all(|c| c.is_ascii_hexdigit())
        && b[24..].iter().all(|c| c.is_ascii_hexdigit())
}

/// Strip common wrapping characters (`"`, `'`, `` ` ``, `:`, `=`) from both ends.
fn strip_delimiters(s: &str) -> &str {
    s.trim_matches(|c| matches!(c, '"' | '\'' | '`' | ':' | '=' | ',' | ';'))
}

/// Strip `{}()[]"'.,;` from both ends of `s`, repeatedly (JSON nests one
/// wrapper inside another).
fn strip_wrappers(s: &str) -> &str {
    s.trim_matches(|c: char| {
        matches!(
            c,
            '{' | '}' | '(' | ')' | '[' | ']' | '"' | '\'' | '`' | '.' | ',' | ';'
        )
    })
}

fn wrapper_strip_repeated(token: &str) -> &str {
    let mut cur = token;
    loop {
        let next = strip_wrappers(cur);
        if next == cur {
            return cur;
        }
        cur = next;
    }
}

/// Yields every candidate value an assignment/wrapper-glued token could
/// contain, for the near-trigger UUID/content-hash exact-shape checks only.
/// See `docs/api/secret_gate.md#value_candidates` for why every `=`/`:` suffix
/// must be tried rather than just the first or last.
fn value_candidates(token: &str) -> impl Iterator<Item = &str> {
    let cur = wrapper_strip_repeated(token);
    std::iter::once(cur).chain(cur.char_indices().filter_map(move |(i, c)| {
        if c == '=' || c == ':' {
            let after = strip_wrappers(&cur[i + c.len_utf8()..]);
            if !after.is_empty() {
                return Some(after);
            }
        }
        None
    }))
}

// ─── Utilities ───────────────────────────────────────────────────────────────

/// Extract a contiguous token (non-whitespace chars) starting at the beginning of `s`.
fn extract_token(s: &str) -> &str {
    let end = s
        .find(|c: char| c.is_whitespace() || c == '\n' || c == '\r')
        .unwrap_or(s.len());
    &s[..end]
}

/// Shannon entropy in bits per character.
///
/// H = -∑ p_i log2(p_i)
fn shannon_entropy(bytes: &[u8]) -> f64 {
    if bytes.is_empty() {
        return 0.0;
    }
    let mut counts = [0u32; 256];
    for &b in bytes {
        counts[b as usize] += 1;
    }
    let len = bytes.len() as f64;
    counts
        .iter()
        .filter(|&&c| c > 0)
        .map(|&c| {
            let p = c as f64 / len;
            -p * p.log2()
        })
        .sum()
}

/// Build a `SecretMatch` from a detector name and the candidate string.
///
/// The masked excerpt is: first 6 chars + "..." + total length.
/// Never includes more than 6 chars of the actual value.
fn build_match(detector: &'static str, candidate: &str) -> SecretMatch {
    let chars: Vec<char> = candidate.chars().collect();
    let preview: String = chars.iter().take(6).collect();
    let masked = format!("{}...{}chars", preview, chars.len());
    SecretMatch {
        detector,
        trigger: None,
        masked,
        location: None,
    }
}

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

    fn opaque_fixture() -> String {
        [
            "ABCDEFGHIJKLMNOPQRSTUVWX",
            "abcdefghijklmnopqrstuvwxyz",
            "0123456789",
        ]
        .concat()
    }

    #[test]
    fn issue_2655_compact_siblings_keep_all_entropy_shapes_member_local() {
        let hex = "0123456789abcdef".repeat(4);
        let opaque = opaque_fixture();
        let members = [
            format!("digest:{hex}"),
            "id:550e8400-e29b-41d4-a716-446655440000".to_owned(),
            format!("sum:sha256-{}=", "A".repeat(43)),
            format!("opaque:{opaque}"),
            format!("path:vault/{opaque}/rotate.md"),
            format!("digest:{}/{}", &hex[..16], &hex[16..32]),
        ];
        for separator in [',', ';', '&'] {
            for member in &members {
                for content in [
                    format!("a_secret:x{separator}{member}"),
                    format!("{member}{separator}a_secret:x"),
                ] {
                    assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
                    assert_eq!(mask_secrets(&content), content);
                }
            }
        }
    }

    #[test]
    fn issue_2655_quote_comma_is_an_inline_member_boundary() {
        let hex = "0123456789abcdef".repeat(4);
        for content in [
            format!(r#"{{"a_secret":"x","digest":"{hex}"}}"#),
            format!(r#"{{"digest":"{hex}","a_secret":"x"}}"#),
        ] {
            assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
            assert_eq!(mask_secrets(&content), content);
        }
    }

    #[test]
    fn issue_2655_external_window_keeps_short_spaced_refusals_and_long_controls() {
        let hex = "0123456789abcdef".repeat(4);
        for content in [
            format!("a_secret:x digest:{hex}"),
            format!("digest:{hex} a_secret:x"),
        ] {
            assert!(
                check(&content).is_err(),
                "short external context: {content}"
            );
        }
        let gap = " documentation".repeat(50);
        assert!(gap.len() > 485);
        for content in [
            format!("a_secret:x{gap} digest:{hex}"),
            format!("digest:{hex}{gap} a_secret:x"),
        ] {
            assert!(check(&content).is_ok(), "long external context: {content}");
            assert_eq!(mask_secrets(&content), content);
        }
    }

    #[test]
    fn issue_2655_credential_assignments_and_nested_carriers_stay_refused() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        let hex = "0123456789abcdef".repeat(4);
        let hash = format!("sha256-{}=", "A".repeat(43));
        let opaque = opaque_fixture();
        for (content, value) in [
            (format!("api_key={id}"), id),
            (format!("secret={hex}"), hex.as_str()),
            (format!("api_key=label={id}"), id),
            (format!("secret=label={hash}"), hash.as_str()),
            (format!("secret:label={hash}"), hash.as_str()),
            (format!("payload=api_key={id}"), id),
            (format!("payload=auth={opaque}"), opaque.as_str()),
            (format!("secret=vault/{opaque}/rotate.md"), opaque.as_str()),
        ] {
            assert!(check(&content).is_err(), "{content}");
            assert!(!mask_secrets(&content).contains(value), "{content}");
        }
    }

    #[test]
    fn issue_2655_later_assignment_does_not_label_an_earlier_value() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        let hex = "0123456789abcdef".repeat(4);
        let opaque = opaque_fixture();
        for value in [id, hex.as_str(), opaque.as_str()] {
            let content = format!("record={value}:a_secret=x");
            assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
            assert_eq!(mask_secrets(&content), content);
        }
    }

    #[test]
    fn issue_2655_refusal_reports_the_matched_members_trigger() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        let opaque = opaque_fixture();
        for (content, trigger) in [
            (format!("a_secret:x,api_key={id}"), "api_key"),
            (format!("api_key:x;auth={opaque}"), "auth"),
            (format!("secret:x&payload=auth={opaque}"), "auth"),
        ] {
            assert_eq!(
                scan(&content).and_then(|matched| matched.trigger),
                Some(trigger),
                "{content}"
            );
        }
    }

    #[test]
    fn issue_2655_masking_continues_through_multiple_members() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        let hex = "0123456789abcdef".repeat(4);
        let benign = "fedcba9876543210".repeat(4);
        let opaque = opaque_fixture();
        for separator in [',', ';', '&'] {
            let content = format!("api_key={id}{separator}digest:{benign}{separator}secret={hex}{separator}auth={opaque}");
            ENTROPY_TOKENIZATION_COUNT.with(|count| count.set(0));
            let masked = mask_secrets(&content);
            assert_eq!(ENTROPY_TOKENIZATION_COUNT.with(|count| count.get()), 1);
            assert_eq!(masked.matches(REDACTION_MARKER).count(), 3, "{masked}");
            for value in [id, hex.as_str(), opaque.as_str()] {
                assert!(!masked.contains(value), "{masked}");
            }
            assert!(masked.contains(&format!("digest:{benign}")), "{masked}");
        }
    }

    #[test]
    fn issue_2655_masking_continues_within_a_governed_member() {
        let first = "0123456789abcdef".repeat(2);
        let second = "fedcba9876543210".repeat(2);
        let content = format!("secret={first}/{second}");
        let masked = mask_secrets(&content);
        assert_eq!(masked.matches(REDACTION_MARKER).count(), 2, "{masked}");
        assert!(!masked.contains(&first));
        assert!(!masked.contains(&second));
    }

    #[test]
    fn issue_2655_known_prefix_under_a_benign_member_stays_refused() {
        let fake = format!("ghp_{}", "A".repeat(36));
        let content = format!(r#"{{"a_secret":"x","digest":"{fake}"}}"#);
        assert_eq!(
            scan(&content).map(|matched| matched.detector),
            Some("github-token")
        );
        assert!(!mask_secrets(&content).contains(&fake));
    }

    #[test]
    fn issue_2655_path_and_revision_guards_do_not_read_sibling_labels() {
        let revision = "0123456789abcdef0123456789abcdef01234567";
        for member in [
            format!("rev:{revision}"),
            format!("source=https://example.test/repo/commit/{revision}"),
            "path=docs/platform/credentials-and-authorization-architecture.md".to_owned(),
        ] {
            let content = format!("a_secret:x,{member}");
            assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
            assert_eq!(mask_secrets(&content), content);
        }
        let credential = format!("secret=https://example.test/repo/commit/{revision}");
        assert!(check(&credential).is_err());
        assert!(!mask_secrets(&credential).contains(revision));
    }

    #[test]
    fn issue_2655_inline_assignment_keeps_unicode_bridge_reconstruction() {
        // The original assignment token clears the existing 24-byte floor;
        // the two bare fragments remain below it and reconstruct to 32 hex.
        let first = "0123456789abcdef01";
        let second = "fedcba98765432";
        let content = format!("secret={first}\u{200b}{second}");
        assert!(check(&content).is_err());
        let masked = mask_secrets(&content);
        assert!(!masked.contains(first));
        assert!(!masked.contains(second));
    }

    #[test]
    fn issue_2655_underscore_carriers_keep_nested_and_padded_forms() {
        let opaque = opaque_fixture();
        for prefix in ["session_secret_", "payload=session_secret_"] {
            for padding in ["", "=", "=="] {
                let content = format!("{prefix}{opaque}{padding}");
                assert!(check(&content).is_err(), "{content}");
                assert!(!mask_secrets(&content).contains(&opaque), "{content}");
            }
        }
    }

    #[test]
    fn issue_2655_inline_bridge_uses_its_final_member() {
        let first = "0123456789abcdef01";
        let second = "fedcba98765432";
        let benign = "fedcba9876543210".repeat(4);
        for prefix in ["a:x".to_owned(), format!("digest:{benign}")] {
            let content = format!("{prefix},secret={first}\u{200b}{second}");
            assert!(check(&content).is_err(), "{content}");
            let masked = mask_secrets(&content);
            assert!(masked.starts_with(&prefix), "{masked}");
            assert!(!masked.contains(first), "{masked}");
            assert!(!masked.ends_with(second), "{masked}");
        }
    }

    #[test]
    fn issue_2655_inline_bridge_stops_at_sibling_boundaries() {
        let first = "0123456789abcdef01";
        let second = "fedcba98765432";
        let benign = "fedcba9876543210".repeat(4);
        for content in [
            format!("secret=x,digest:{first}\u{200b}{second}"),
            format!("secret={first},digest:x\u{200b}{second}"),
            format!("secret={first},digest:{benign}\u{200b}{second}"),
            format!("{first}\u{200b}digest:x,secret={second}"),
        ] {
            assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
            assert_eq!(mask_secrets(&content), content);
        }
    }

    #[test]
    fn issue_2655_mask_budget_charges_compact_token_prefix_revisits() {
        let hex = "0123456789abcdef".repeat(2);
        let tail = format!(",secret={hex}").repeat(200);
        let content = format!("padding:{}{tail}", "a".repeat(900_000));
        let (spans, work) = collect_mask_spans(&content);
        assert!(
            work >= content.len() * 2,
            "each continuation revisits the full compact token"
        );
        assert!(work <= MAX_MASK_SCAN_WORK_BYTES);
        assert_eq!(spans.last().map(|span| span.1), Some(content.len()));
        let masked = mask_secrets(&content);
        assert!(!masked.contains(&hex));
        assert!(masked.matches(REDACTION_MARKER).count() < 200);
        assert!(masked.ends_with(REDACTION_MARKER));
    }

    #[test]
    fn issue_2655_later_assignment_bridge_preserves_earlier_record_value() {
        let benign = "0123456789abcdef".repeat(4);
        let first = "a1b2c3d4e5f6071829";
        let second = "30415263748596";
        let prefix = format!("record={benign}:a_secret=");
        let content = format!("{prefix}{first}\u{200b}{second}");
        assert_eq!(
            scan(&content).and_then(|matched| matched.trigger),
            Some("secret")
        );
        let masked = mask_secrets(&content);
        assert!(masked.starts_with(&prefix), "{masked}");
        assert!(!masked.contains(first), "{masked}");
        assert!(!masked.contains(second), "{masked}");
        assert_eq!(masked.matches(REDACTION_MARKER).count(), 2, "{masked}");
    }
}

// ─── Tests ───────────────────────────────────────────────────────────────────

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

    fn github_fine_grained_pat_fixture() -> String {
        format!("github_pat_{}", "A".repeat(82))
    }

    fn openai_project_key_fixture() -> String {
        format!("sk-proj-{}", "A".repeat(80))
    }

    fn anthropic_api_key_fixture() -> String {
        format!("sk-ant-api03-{}AA", "A".repeat(93))
    }

    #[test]
    fn blocks_aws_akia() {
        // FAKE key: prefix is real shape, 16-char suffix invented.
        let fake = "AKIAFAKEKEY1234567890";
        assert!(scan(fake).is_some(), "AKIA must be caught");
        let m = scan(fake).unwrap();
        assert_eq!(m.detector, "aws-access-key-id");
        // Masked excerpt must not echo the full key.
        assert!(
            !m.masked.contains("FAKEKEY1234567890"),
            "must not echo the secret: {}",
            m.masked
        );
    }

    #[test]
    fn blocks_aws_asia() {
        let fake = "ASIAFAKEKEY00000000000";
        let m = scan(fake);
        assert!(m.is_some(), "ASIA must be caught");
        assert_eq!(m.unwrap().detector, "aws-access-key-id");
    }

    #[test]
    fn blocks_github_ghp() {
        // 36 chars total to pass min_len.
        let fake = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
        assert!(scan(fake).is_some(), "ghp_ must be caught");
    }

    #[test]
    fn blocks_github_gho() {
        let fake = "gho_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB";
        assert!(scan(fake).is_some(), "gho_ must be caught");
    }

    #[test]
    fn blocks_github_pat() {
        let fake = github_fine_grained_pat_fixture();
        assert!(scan(&fake).is_some(), "github_pat_ must be caught");
    }

    #[test]
    fn blocks_openai_sk() {
        let fake = "sk-aaaaaabbbbbbccccccddddddeeeeeeffffgg";
        assert!(scan(fake).is_some(), "sk- must be caught");
    }

    #[test]
    fn blocks_anthropic_sk_ant() {
        let fake = anthropic_api_key_fixture();
        assert!(scan(&fake).is_some(), "sk-ant- must be caught");
        assert_eq!(scan(&fake).unwrap().detector, "anthropic-api-key");
    }

    #[test]
    fn vendor_prefix_minimums_allow_short_documentation_fragments() {
        let fragments = [
            "github_pat_[A-Za-z0-9_]{82}".to_owned(),
            "sk-proj-[A-Za-z0-9_-]{80,}".to_owned(),
            "sk-ant-api03-[A-Za-z0-9_-]{93}AA".to_owned(),
            "github_pat_FAKE_CANARY".to_owned(),
            "sk-ant-api03-FAKE_CANARY".to_owned(),
            format!("github_pat_{}", "A".repeat(81)),
            format!("sk-proj-{}", "A".repeat(79)),
            format!("sk-ant-api03-{}AA", "A".repeat(92)),
        ];

        for fragment in fragments {
            assert!(
                check(&fragment).is_ok(),
                "short documentation fragment must pass: {fragment}, got {:?}",
                scan(&fragment)
            );
        }
    }

    #[test]
    fn vendor_prefix_minimums_keep_plausible_keys_blocked() {
        let github = github_fine_grained_pat_fixture();
        let openai = openai_project_key_fixture();
        let anthropic = anthropic_api_key_fixture();

        for (candidate, detector) in [
            (github.as_str(), "github-token"),
            (openai.as_str(), "openai-api-key"),
            (anthropic.as_str(), "anthropic-api-key"),
        ] {
            let matched = scan(candidate).expect("plausible-length vendor key must remain blocked");
            assert_eq!(matched.detector, detector);
        }
    }

    #[test]
    fn short_specialized_sk_prefix_does_not_hide_later_generic_key() {
        let short_vendor_fragment = format!("sk-proj-{}", "A".repeat(79));
        let generic_key = format!("sk-{}", "A1".repeat(20));
        let content = format!("{short_vendor_fragment} {generic_key}");

        let (matched, detector) =
            scan_match(&content).expect("later generic sk key must remain detectable");
        assert_eq!(matched, generic_key);
        assert_eq!(detector, "openai-api-key");
    }

    #[test]
    fn glued_short_specialized_prefix_does_not_hide_later_generic_key() {
        let generic_key = format!("sk-{}A", "A1".repeat(21));
        let content = format!("sk-proj-X,{generic_key}");

        assert!(
            check(&content).is_err(),
            "a generic key after a rejected vendor prefix must remain blocked"
        );
        let masked = mask_secrets(&content).into_owned();
        assert!(
            !masked.contains(&generic_key),
            "the later generic key must not survive masking: {masked}"
        );
        assert!(
            masked.contains(REDACTION_MARKER),
            "the later generic key must be replaced: {masked}"
        );
    }

    #[test]
    fn blocks_stripe_live() {
        let fake = "sk_live_FAKESTRIPE0000000000000"; // gitleaks:allow
        assert!(scan(fake).is_some(), "sk_live_ must be caught");
        assert_eq!(scan(fake).unwrap().detector, "stripe-secret-key");
    }

    #[test]
    fn blocks_stripe_restricted() {
        let fake = "rk_live_FAKESTRIPE0000000000000"; // gitleaks:allow
        assert!(scan(fake).is_some(), "rk_live_ must be caught");
        assert_eq!(scan(fake).unwrap().detector, "stripe-restricted-key");
    }

    #[test]
    fn blocks_fly_flyv1() {
        let fake = "FlyV1 FAKEFLYTOKEN000000000000000000";
        assert!(scan(fake).is_some(), "FlyV1 must be caught");
        assert_eq!(scan(fake).unwrap().detector, "fly-token");
    }

    #[test]
    fn short_flyv1_marker_does_not_hide_later_token() {
        let content = "FlyV1 ab FlyV1 FAKEFLYTOKEN000000000000000000";
        let (matched, detector) = scan_match(content).expect("later FlyV1 token must be detected");
        assert_eq!(detector, "fly-token");
        assert_eq!(matched, "FlyV1 FAKEFLYTOKEN000000000000000000");
        assert_eq!(
            matched.as_ptr() as usize - content.as_ptr() as usize,
            content.rfind("FlyV1 ").unwrap()
        );
        assert_eq!(scan(content).unwrap().detector, "fly-token");
    }

    #[test]
    fn non_boundary_flyv1_marker_does_not_hide_later_token() {
        for content in [
            "xFlyV1 abc FlyV1 FAKEFLYTOKEN000000000000000000",
            "xFlyV1 FAKE FlyV1 FAKEFLYTOKEN000000000000000000",
        ] {
            let (matched, detector) =
                scan_match(content).expect("later FlyV1 token must be detected");
            assert_eq!(detector, "fly-token");
            assert_eq!(matched, "FlyV1 FAKEFLYTOKEN000000000000000000");
            assert_eq!(
                matched.as_ptr() as usize - content.as_ptr() as usize,
                content.rfind("FlyV1 ").unwrap()
            );
            assert_eq!(scan(content).unwrap().detector, "fly-token");
        }
    }

    #[test]
    fn blocks_fly_fm2() {
        let fake = "fm2_FAKEFLYTOKEN00000000000000000";
        assert!(scan(fake).is_some(), "fm2_ must be caught");
        assert_eq!(scan(fake).unwrap().detector, "fly-token");
    }

    #[test]
    fn blocks_vercel_token() {
        let fake = "vercel_FAKETOKEN00000000000000000";
        assert!(scan(fake).is_some(), "vercel_ must be caught");
        assert_eq!(scan(fake).unwrap().detector, "vercel-token");
    }

    #[test]
    fn prefix_detectors_allow_lowercase_source_filenames() {
        for &(_, needle, min_len) in PREFIX_DETECTORS {
            let padding_len = min_len.saturating_sub(needle.len() + "provider_.py".len());
            let filename_body = format!("provider_{}.py", "a".repeat(padding_len));
            let candidate = format!("{needle}{filename_body}");
            assert!(
                candidate.len() >= min_len,
                "negative control must exercise {needle}'s length tier"
            );
            assert!(
                find_prefix_token(&candidate, needle, min_len).is_none(),
                "lowercase source filename must not match prefix {needle}: {candidate}"
            );
            assert!(
                check(&candidate).is_ok(),
                "lowercase source filename must pass the canonical scanner: {candidate}, got {:?}",
                scan(&candidate)
            );
        }
    }

    #[test]
    fn prefix_detectors_keep_value_shaped_payloads_with_source_suffixes() {
        for &(_, needle, min_len) in PREFIX_DETECTORS {
            let required_payload_len = min_len.saturating_sub(needle.len()).max(2);
            let value_payload = "A1".repeat(required_payload_len.div_ceil(2));
            let candidate = format!("{needle}{value_payload}.py");
            assert!(
                find_prefix_token(&candidate, needle, min_len).is_some(),
                "uppercase/digit value evidence must preserve prefix {needle}: {candidate}"
            );
        }
    }

    #[test]
    fn prefix_detectors_keep_lowercase_single_run_payloads_with_source_suffixes() {
        for &(_, needle, min_len) in PREFIX_DETECTORS {
            let required_payload_len = min_len.saturating_sub(needle.len()).max(24);
            let value_payload = "a".repeat(required_payload_len);
            let candidate = format!("{needle}{value_payload}.py");
            assert!(
                find_prefix_token(&candidate, needle, min_len).is_some(),
                "an extension alone must not exempt prefix {needle}: {candidate}"
            );
        }
    }

    #[test]
    fn allows_vercel_prefixed_source_filename_on_every_scanner_surface() {
        let content = "review `vercel_deployment_monitoring_adapter.py` before release";

        assert!(check(content).is_ok(), "write gate must allow filename");
        assert!(scan(content).is_none(), "scanner must not report filename");
        assert_eq!(
            mask_secrets(content).as_ref(),
            content,
            "masking surface must preserve the filename byte-for-byte"
        );
    }

    #[test]
    fn admits_source_citation_line_reference_and_still_blocks_random_payload() {
        // Arm 1 — admitted: a file-and-line citation, both the single-line and
        // range forms, across two different source extensions, including a
        // path-bearing stem (`/` is in the allowed stem punctuation set).
        let admitted = [
            "vercel_deployment_monitor.py:412",
            "vercel_deployment_monitor.py:412-418",
            "vercel_src/runtime/checkpoint_loader.rs:97-103",
        ];
        for content in admitted {
            assert!(
                find_prefix_token(content, "vercel_", 20).is_none(),
                "file-and-line citation must not be flagged as a credential: {content}"
            );
            assert!(
                check(content).is_ok(),
                "file-and-line citation must pass the write gate: {content}, got {:?}",
                scan(content)
            );
        }

        // Arm 2 — must-FAIL control, in the SAME test as arm 1: a provider
        // prefix followed by an ordinary random-looking value is still a
        // credential. This is the arm a loose "trailing digits anywhere"
        // suffix match would silently stop catching.
        let random_payload = "vercel_aB3xQ9mK7pL2wZ8nR4tY6uV1"; // gitleaks:allow
        assert_eq!(random_payload.len() - "vercel_".len(), 24);
        assert!(
            find_prefix_token(random_payload, "vercel_", 20).is_some(),
            "random payload after the provider prefix must still be flagged: {random_payload}"
        );
        assert_eq!(
            scan(random_payload).map(|matched| matched.detector),
            Some("vercel-token"),
            "random-looking payload after the provider prefix must still be scanned as a credential"
        );
    }

    #[test]
    fn source_citation_line_reference_boundary_arms_still_refused() {
        let needle = "vercel_";
        let cases = [
            "vercel_deployment_monitor.py:4a2", // non-digit byte in the run
            "vercel_deployment_monitor.py:12-", // empty second digit run
            "vercel_deployment_monitor.py:12-34-56", // more than one '-'
            // Refused by the SEPARATOR predicate, not the digit one: this stem
            // carries no `_`, `-`, `/` or `.`. A real shape, but it cannot
            // isolate the all-lowercase rule.
            "vercel_deployment2monitor.py:412",
            // Digit inside the stem WITH a separator present, so the
            // all-lowercase predicate is the only thing refusing it. This is
            // the isolating arm for that predicate: loosen it to tolerate
            // digits and this case alone is admitted.
            "vercel_deployment2_monitor.py:412",
        ];
        for token in cases {
            assert!(
                !is_filename_shaped_prefix_match(token, needle),
                "must still be refused: {token}"
            );
        }

        // A bare trailing colon is NOT a boundary case of the line-reference
        // grammar; it is sentence punctuation, and the generic trim has always
        // removed it before this function looks at anything. It was admitted
        // before line references were understood here and must stay admitted:
        // this change widens what the carve-out accepts and narrows nothing.
        // Without this arm, a later reading of the boundary list above would
        // conclude the colon belongs in the grammar and quietly turn a prose
        // citation into a refusal.
        assert!(
            is_filename_shaped_prefix_match("vercel_deployment_monitor.py:", needle),
            "a trailing colon is prose punctuation and was always trimmed"
        );
    }

    #[test]
    fn blocks_slack_xoxb() {
        let fake = "xoxb-FAKE-SLACKTOKEN-000000000000000000000000";
        assert!(scan(fake).is_some(), "xoxb- must be caught");
        assert_eq!(scan(fake).unwrap().detector, "slack-token");
    }

    #[test]
    fn blocks_pem_private_key() {
        // Split the header so the literal detector-trigger string is not present
        // verbatim in source — pre-commit's detect-private-key hook would fire.
        // The gate detects it at runtime because scan() sees the assembled string.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let fake = format!("{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----", header);
        assert!(scan(&fake).is_some(), "PEM private key must be caught");
        assert_eq!(scan(&fake).unwrap().detector, "pem-private-key");
    }

    #[test]
    fn blocks_pem_ec_private_key() {
        let header = ["-----BEGIN EC", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let fake = format!("{}\nMHQCAQEE\u{2026}\n-----END EC PRIVATE KEY-----", header);
        assert!(scan(&fake).is_some(), "EC PEM must be caught");
    }

    #[test]
    fn pem_header_alone_is_a_mention_not_a_key() {
        // A documentation page names the header label with no END marker and
        // no base64 under it: the format is mentioned, no key is present.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let doc = format!(
            "A PEM private key file starts with the line `{}` and the key\n\
             material follows it on wrapped lines. Keep such files out of chat.\n",
            header
        );
        assert!(
            scan(&doc).is_none(),
            "a header with no body must not be reported as a key"
        );
        // Positive control on the same predicate: the same header with a
        // matching END marker is a block, however short its body.
        let block = format!("{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----", header);
        assert_eq!(scan(&block).unwrap().detector, "pem-private-key");
    }

    #[test]
    fn pem_many_headers_without_bodies_are_accepted() {
        // Eight header mentions across a page (the second reported shape),
        // none followed by an END marker or a base64 line.
        let header = ["-----BEGIN EC", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let mut doc = String::new();
        for kind in [
            "RSA",
            "EC",
            "DSA",
            "OPENSSH",
            "ENCRYPTED",
            "",
            "PGP",
            "X25519",
        ] {
            doc.push_str(&format!(
                "Use `-----BEGIN {} PRIVATE KEY-----` for this key type.\n",
                kind
            ));
        }
        assert!(doc.matches("-----BEGIN").count() == 8);
        assert!(scan(&doc).is_none(), "{:?}", scan(&doc));
        // Same page with one real block appended is refused, and the
        // candidate is that block, not the page from the first mention down.
        let block = format!("{header}\nMHQCAQEE\u{2026}\n-----END EC PRIVATE KEY-----\n");
        let with_block = format!("{doc}{block}");
        let m = scan(&with_block).unwrap();
        assert_eq!(m.detector, "pem-private-key");
        assert!(
            m.masked
                .ends_with(&format!("...{}chars", block.chars().count())),
            "masked: {}",
            m.masked
        );
    }

    #[test]
    fn pem_header_with_base64_body_and_no_end_marker_is_refused() {
        // Key material pasted without its END line is still a key.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let body_line = "MIIEowIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF8PbnGYPYFqHlZ4kUmUqQ7fEd7Uw";
        let trailing =
            "and then a long paragraph of ordinary prose that is not part of the key block at all";
        let text = format!("{header}\n{body_line}\n{body_line}\n\n{trailing}\n");
        let m = scan(&text).expect("a header with a base64 body is a key");
        assert_eq!(m.detector, "pem-private-key");
        // The candidate is bounded to the header plus its base64 lines.
        let block_len = header.chars().count() + 1 + (body_line.len() + 1) * 2;
        let reported_len: usize = m
            .masked
            .trim_end_matches("chars")
            .rsplit("...")
            .next()
            .and_then(|s| s.parse().ok())
            .expect("masked preview ends in the candidate length");
        assert_eq!(reported_len, block_len, "masked: {}", m.masked);
        // A short base64 tail alone (below key-block width) is not a body.
        let short = format!("{header}\nMIIEowIBAAKCAQEA\n{trailing}\n");
        assert!(scan(&short).is_none(), "{:?}", scan(&short));
        // After a full-width line, a short final line is the end of the block
        // and stays inside the candidate rather than surviving past it.
        let tail = "MIIEowIBAAKCAQEA";
        let with_tail = format!("{header}\n{body_line}\n{tail}\n{trailing}\n");
        let m = scan(&with_tail).expect("a full line plus a short tail is a key");
        let tail_len = header.chars().count() + 1 + body_line.len() + 1 + tail.len() + 1;
        assert!(
            m.masked.ends_with(&format!("...{tail_len}chars")),
            "masked: {}",
            m.masked
        );
        let masked = mask_secrets(&with_tail);
        assert!(!masked.contains(tail), "tail survived masking: {masked}");
    }

    #[test]
    fn pem_block_inside_serialized_json_is_still_caught_and_a_mention_is_not() {
        // A note's properties or a stream payload reach the gate as compact
        // JSON, where every newline is the two-character escape. The same
        // rules apply on that form.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let body_line = "MIIEowIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF8PbnGYPYFqHlZ4kUmUqQ7fEd7Uw";
        let block = serde_json::json!({"payload": format!("{header}\n{body_line}\n{body_line}")});
        let serialized = serde_json::to_string(&block).unwrap();
        assert!(
            serialized.contains("\\n"),
            "fixture must carry escaped newlines"
        );
        let m = scan(&serialized).expect("a key block in serialized JSON is a key");
        assert_eq!(m.detector, "pem-private-key");
        // Bounded to the block: the closing quote and brace are not part of it.
        let block_len = header.chars().count() + 2 + (body_line.len() + 2) + body_line.len();
        assert!(
            m.masked.ends_with(&format!("...{block_len}chars")),
            "masked: {}",
            m.masked
        );
        let with_end = serde_json::json!({
            "payload": format!("{header}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----\ntrailing")
        });
        let serialized = serde_json::to_string(&with_end).unwrap();
        assert_eq!(scan(&serialized).unwrap().detector, "pem-private-key");

        let mention = serde_json::json!({
            "doc": format!("A key file starts with `{header}` and continues on wrapped lines.")
        });
        let serialized = serde_json::to_string(&mention).unwrap();
        assert!(scan(&serialized).is_none(), "{:?}", scan(&serialized));
    }

    #[test]
    fn pem_block_after_an_unrelated_begin_marker_is_still_caught() {
        // A certificate header earlier in the text must not hide the key
        // block behind it, and the candidate starts at the key header.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let text = format!(
            "-----BEGIN CERTIFICATE-----\nMIIB\u{2026}\n-----END CERTIFICATE-----\n{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----\n",
            header
        );
        let m = scan(&text).expect("the key block must be caught");
        assert_eq!(m.detector, "pem-private-key");
        assert!(
            !m.masked.starts_with("-----BEGIN C"),
            "candidate must start at the key header: {}",
            m.masked
        );
    }

    #[test]
    fn blocks_age_secret_key() {
        // AGE-SECRET-KEY- followed by 59 base32 chars (Bech32m body).
        let fake = "AGE-SECRET-KEY-1QQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQQ";
        assert!(scan(fake).is_some(), "AGE-SECRET-KEY- must be caught");
        assert_eq!(scan(fake).unwrap().detector, "age-secret-key");
    }

    #[test]
    fn blocks_jwt_triple() {
        // Synthetic JWT structure: header.payload.signature (no real key).
        let fake = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.FAKE_SIG_XXXXXXXXXXXX"; // gitleaks:allow
        assert!(scan(fake).is_some(), "JWT triple must be caught");
        assert_eq!(scan(fake).unwrap().detector, "jwt");
    }

    #[test]
    fn blocks_url_userinfo() {
        let fake = "postgresql://dbuser:S3cr3tP4ss@db.example.com:5432/mydb";
        assert!(scan(fake).is_some(), "URL userinfo must be caught");
        assert_eq!(scan(fake).unwrap().detector, "url-userinfo");
    }

    #[test]
    fn url_userinfo_placeholder_refusal_explains_effective_remedies() {
        for content in [
            "postgresql://dbuser:<PASSWORD>@db.example.com:5432/mydb",
            "postgresql://<USER>:<PASSWORD>@db.example.com:5432/mydb",
            "redis://:<PASSWORD>@cache.example.com:6379",
        ] {
            let error = check(content).expect_err("URL credential placeholders still match");
            let RuntimeError::SecretDetected(matched) = &error else {
                panic!("expected a secret refusal, got {error}");
            };
            assert_eq!(matched.detector, "url-userinfo");
            let rendered = error.to_string();
            for guidance in [
                "Placeholders in URL credential positions still match",
                "Replace the whole URL",
                "environment-variable name or config key",
                "remove the entire user/password segment",
            ] {
                assert!(
                    rendered.contains(guidance),
                    "missing {guidance:?}: {rendered}"
                );
            }
            assert!(!rendered.contains(content), "refusal must not echo the URL");
        }
    }

    #[test]
    fn url_userinfo_guidance_remedies_are_accepted() {
        for content in [
            "Use the DATABASE_URL environment variable.",
            "Use the database.connection_url config key.",
            "postgresql://db.example.com:5432/mydb",
            "redis://cache.example.com:6379",
        ] {
            assert!(
                check(content).is_ok(),
                "URL reference or URL without credentials must be accepted: {content:?}"
            );
        }
    }

    #[test]
    fn blocks_and_masks_url_userinfo_with_short_passwords() {
        for password in ["a", "ab", "abc"] {
            let content = format!(
                "gate backend probe failed: postgres://svc:{password}@internal-host refused"
            );

            let detected = scan(&content).expect("short URL password must be detected");
            assert_eq!(detected.detector, "url-userinfo");
            assert!(
                check(&content).is_err(),
                "write gate must block {content:?}"
            );
            assert_eq!(
                bounded_masked_log_text(&content),
                "gate backend probe failed: ***MASKED*** refused",
                "log boundary must mask {content:?}"
            );
        }
    }

    #[test]
    fn keeps_url_without_userinfo() {
        let content = "gate backend probe failed: postgres://host:8080/path refused";

        assert!(check(content).is_ok(), "host:port is not URL userinfo");
        assert_eq!(bounded_masked_log_text(content), content);
    }

    #[test]
    fn blocks_and_masks_empty_username_url_passwords() {
        // Standard empty-user connection strings: the password is the
        // credential whether or not a username precedes the colon.
        for password in ["a", "ab", "%40", "密码"] {
            let content =
                format!("gate backend probe failed: redis://:{password}@internal-host refused");

            let detected = scan(&content).expect("empty-username URL password must be detected");
            assert_eq!(detected.detector, "url-userinfo");
            assert!(
                check(&content).is_err(),
                "write gate must block {content:?}"
            );
            assert_eq!(
                bounded_masked_log_text(&content),
                "gate backend probe failed: ***MASKED*** refused",
                "log boundary must mask {content:?}"
            );
        }
    }

    #[test]
    fn keeps_colon_at_pairs_outside_the_authority() {
        // An `@` past the authority boundary is path/query/fragment text,
        // not userinfo: `host/a:x@next` must not read as user `host/a` with
        // password `x`.
        for content in [
            "see https://host/a:x@next for details",
            "see https://host?time=12:30@zone for details",
            "see https://host#frag:1@anchor for details",
        ] {
            assert!(
                check(content).is_ok(),
                "path/query/fragment `:`+`@` text is not userinfo: {content:?}"
            );
            assert_eq!(bounded_masked_log_text(content), content);
        }
    }

    #[test]
    fn blocks_high_entropy_near_bearer_word() {
        // 32 random-looking base64 chars adjacent to the word "bearer".
        let fake = "Bearer token: Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
        assert!(
            scan(fake).is_some(),
            "high-entropy value near 'bearer' must be caught"
        );
        assert_eq!(scan(fake).unwrap().detector, "high-entropy-token");
    }

    #[test]
    fn blocks_high_entropy_near_secret_word() {
        let fake = "secret=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
        assert!(
            scan(fake).is_some(),
            "high-entropy value near 'secret' must be caught"
        );
    }

    #[test]
    fn error_message_masks_secret() {
        let fake = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
        let m = scan(fake).unwrap();
        // Masked form: first 6 chars + "...N chars".
        // Must NOT contain the full suffix.
        let masked = &m.masked;
        assert!(
            !masked.contains("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"),
            "mask must not echo the full secret value; got: {masked}"
        );
        // Must start with "ghp_AA" (first 6 chars of the token).
        assert!(
            masked.starts_with("ghp_AA"),
            "mask must show first 6 chars; got: {masked}"
        );
    }

    // ── False-positive suite ─────────────────────────────────────────────────

    #[test]
    fn allows_sha256_hex() {
        // 64-char lowercase hex — typical sha256 digest.
        let sha = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
        assert!(
            scan(sha).is_none(),
            "sha256 hex must pass (allowlisted); fired: {:?}",
            scan(sha)
        );
    }

    #[test]
    fn allows_uuid() {
        let uuid = "550e8400-e29b-41d4-a716-446655440000";
        assert!(
            scan(uuid).is_none(),
            "UUID must pass; fired: {:?}",
            scan(uuid)
        );
    }

    #[test]
    fn allows_git_sha() {
        // 40-char lowercase git SHA.
        let sha = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        assert!(
            scan(sha).is_none(),
            "git SHA must pass; fired: {:?}",
            scan(sha)
        );
    }

    #[test]
    fn allows_normal_prose() {
        let prose =
            "The FlashAttention paper introduces IO-aware tiling for transformer self-attention.";
        assert!(scan(prose).is_none(), "normal prose must pass");
    }

    #[test]
    fn allows_code_snippet() {
        let code = r#"fn create_entity(name: &str, kind: &str) -> RuntimeResult<Entity> {
    self.validate_entity_kind(kind)?;
    Ok(Entity::new("local", kind, name))
}"#;
        assert!(
            scan(code).is_none(),
            "code snippet must pass; fired: {:?}",
            scan(code)
        );
    }

    #[test]
    fn allows_long_url_without_credentials() {
        let url = "https://docs.example.com/api/v2/entities?kind=concept&limit=100";
        assert!(scan(url).is_none(), "URL without userinfo must pass");
    }

    #[test]
    fn allows_base64_image_stub() {
        // Realistic short base64 data URI stub — no trigger words, below threshold length.
        let b64 = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQ";
        assert!(
            scan(b64).is_none(),
            "base64 image stub without trigger word must pass; fired: {:?}",
            scan(b64)
        );
    }

    #[test]
    fn allows_long_plain_url() {
        let url = "https://api.github.com/repos/ohdearquant/khive/pulls/76/comments?per_page=100";
        assert!(
            scan(url).is_none(),
            "plain URL must pass; fired: {:?}",
            scan(url)
        );
    }

    #[test]
    fn allows_manifest_content_hash() {
        // A string like what appears in Cargo.lock or npm lockfiles.
        let line =
            "checksum = \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\"";
        assert!(
            scan(line).is_none(),
            "manifest content hash line must pass; fired: {:?}",
            scan(line)
        );
    }

    #[test]
    fn masked_excerpt_format() {
        let fake = "AKIAFAKEKEY1234567890";
        let m = scan(fake).unwrap();
        // Format: first6...Nchars
        assert!(m.masked.contains("..."), "masked must contain '...'");
        assert!(m.masked.ends_with("chars"), "masked must end with 'chars'");
    }

    // ── Gate function ────────────────────────────────────────────────────────

    #[test]
    fn check_returns_ok_for_safe_content() {
        assert!(check("A normal memory note about LoRA.").is_ok());
    }

    #[test]
    fn check_returns_err_for_secret() {
        let fake = "AKIAFAKEKEY1234567890";
        let result = check(fake);
        assert!(result.is_err(), "check must fail for AKIA key");
        let err = result.unwrap_err();
        assert!(
            matches!(err, RuntimeError::SecretDetected(_)),
            "error variant must be SecretDetected"
        );
    }

    // ── Entropy helpers ──────────────────────────────────────────────────────

    #[test]
    fn entropy_of_uniform_string_is_zero() {
        let s = "aaaaaaaaaaaaaaaa";
        assert!(shannon_entropy(s.as_bytes()) < 0.01);
    }

    #[test]
    fn entropy_of_random_bytes_is_high() {
        // A truly random-looking string should exceed 4.5 bits/char.
        let s = b"X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // 32 mixed base64 chars
        assert!(shannon_entropy(s) > 4.5, "entropy={}", shannon_entropy(s));
    }

    #[test]
    fn cjk_prose_near_trigger_is_not_flagged() {
        // Regression: a multibyte CJK run (~19 chars = 57 bytes) clears the
        // byte-length floor, and `shannon_entropy` over UTF-8 bytes reads it as
        // high-entropy — so a Chinese title near the `auth` trigger word used to
        // false-positive as `high-entropy-token`.  Non-ASCII tokens are now
        // skipped by the entropy heuristic: real base64/hex credentials are
        // ASCII, so this cannot hide a secret.
        let content = "更新 auth 配置数据库连接管理系统核心模块设计文档";
        assert!(
            check(content).is_ok(),
            "CJK prose near a trigger word must not be flagged as a secret"
        );
    }

    #[test]
    fn ascii_secret_near_trigger_still_flagged() {
        // The non-ASCII skip must NOT weaken detection of genuine ASCII
        // high-entropy credentials near a trigger word.
        let content = "api_key X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1";
        assert!(
            check(content).is_err(),
            "ASCII high-entropy token near a trigger word must still be blocked"
        );
    }

    #[test]
    fn ascii_secret_in_cjk_context_does_not_panic_and_is_flagged() {
        // The ±120-byte trigger window around an ASCII token can land in the
        // middle of a multibyte CJK character when the token is embedded in
        // non-Latin prose.  Slicing on a non-char-boundary would panic — the
        // window bounds are snapped via `floor_char_boundary`.  Detection of
        // the genuine ASCII secret must still fire.
        let cjk = "数据库连接管理系统核心模块设计文档".repeat(6); // 17 chars × 6 = 306 bytes
                                                                  // The leading single-byte `x` breaks 3-byte CJK alignment so the window
                                                                  // start (token_offset - 120) lands mid-character without the snap.
        let content = format!("{cjk}x api_key X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1 {cjk}");
        assert!(
            check(&content).is_err(),
            "ASCII secret in CJK context must still be blocked (and must not panic)"
        );
    }

    #[test]
    fn ascii_secret_glued_to_cjk_is_still_flagged() {
        // Regression: a prefixless high-entropy credential glued (no ASCII
        // whitespace) to CJK text, CJK brackets/quotes, a fullwidth space, or a
        // fullwidth colon used to slip through, because the whole whitespace token
        // contained a non-ASCII byte and was skipped wholesale.  Non-ASCII is now
        // a token delimiter, so the ASCII credential run is isolated and
        // entropy-checked while the surrounding ±120-byte window still sees the
        // trigger word.
        let secret = "X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
        let cases = [
            format!("api_key {secret}数据"),     // CJK suffix glued to the token
            format!("api_key 「{secret}」"),     // CJK brackets wrap the token
            format!("api_key　{secret}"),        // U+3000 ideographic space separator
            format!("api_key：{secret}"),        // U+FF1A fullwidth colon separator
            format!("数据{secret}更新 api_key"), // CJK-glued prefix, trigger after
        ];
        for content in &cases {
            assert!(
                check(content).is_err(),
                "ASCII secret glued to CJK must be blocked: {content:?}"
            );
        }
    }

    #[test]
    fn high_entropy_ascii_run_without_trigger_is_not_flagged() {
        // The non-ASCII-as-delimiter change must not weaken the trigger-context
        // discipline: a high-entropy ASCII run isolated from CJK prose but NOT
        // near a credential trigger word is still allowed (only the tokenizer
        // changed, not the `near_trigger` gate).
        let secret = "X9kZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
        let content = format!("数据库连接{secret}核心模块设计文档");
        assert!(
            check(&content).is_ok(),
            "high-entropy ASCII run with no trigger word must not be flagged"
        );
    }

    #[test]
    fn known_prefix_secret_glued_after_cjk_is_still_flagged() {
        // A Layer-1 known-prefix secret glued directly after
        // CJK prose (no ASCII whitespace) was missed, because the prefix boundary
        // check used `is_alphanumeric` — which Rust counts true for CJK — so the
        // preceding ideograph was not treated as a delimiter.  These credentials
        // must be caught with no nearby ASCII trigger word, on the left side too.
        let cases = [
            "数据AKIAIOSFODNN7EXAMPLE".to_owned(), // gitleaks:allow
            format!("令牌{}", github_fine_grained_pat_fixture()),
            format!("密钥{}", anthropic_api_key_fixture()),
            "配置FlyV1 fm2_AAAABBBBCCCCDDDD".to_owned(), // gitleaks:allow
        ];
        for content in &cases {
            assert!(
                check(content).is_err(),
                "known-prefix secret glued after CJK must be blocked: {content:?}"
            );
        }
    }

    #[test]
    fn url_userinfo_after_cjk_does_not_panic_and_is_flagged() {
        // A credential URL glued after CJK prose panicked,
        // because scheme_start was (separator byte index + 1) — one byte into a
        // multibyte CJK separator — and the slice fell on a non-char boundary.
        // The public check() API must return a controlled error, never panic.
        let cases = [
            "数据postgresql://dbuser:S3cr3tP4ss@db.example.com/db", // gitleaks:allow
            "配置mysql://root:hunter2pw@10.0.0.1:3306/app",         // gitleaks:allow
            "连接redis://svc:V3ryS3cretPw@cache.internal:6379",     // gitleaks:allow
        ];
        for content in cases {
            assert!(
                check(content).is_err(),
                "credential URL after CJK must be blocked, not panic: {content:?}"
            );
        }
    }

    #[test]
    fn non_ascii_glued_token_trigger_is_still_flagged() {
        // `token=`/`token:`/standalone `token` glued directly
        // after non-ASCII prose was missed because has_standalone_token /
        // has_token_assignment used is_alphanumeric for the word boundary — CJK,
        // accented letters, and fullwidth digits all count as alphanumeric in
        // Rust, so the preceding char was not seen as a boundary and the `token`
        // trigger was suppressed, leaving the high-entropy value unflagged.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let blocked = [
            format!("数据token={opaque}"),    // CJK + assignment form, ASCII '='
            format!("配置token: {opaque}"),   // CJK + assignment form, ASCII ':'
            format!("密钥token {opaque}"),    // CJK + standalone-word form
            format!("résumétoken: {opaque}"), // accented letter before `token`
            format!("１token: {opaque}"),     // fullwidth digit before `token`
        ];
        for content in &blocked {
            assert!(
                check(content).is_err(),
                "non-ASCII-glued token trigger must flag the value: {content:?}"
            );
        }
        // Compound identifiers stay excluded — the `_` boundary rule is unchanged
        // and an ASCII letter before `token` is still a continuation, so these
        // (including the pure-ASCII `servicetoken:`) must still pass.
        let allowed = [
            format!("数据next_token: {opaque}"),
            format!("数据token_count: {opaque}"),
            format!("servicetoken: {opaque}"),
        ];
        for content in &allowed {
            assert!(
                check(content).is_ok(),
                "compound token identifier must not be flagged: {content:?}"
            );
        }
    }

    #[test]
    fn allowlist_passes_sha256() {
        // A plain sha256 hex digest passes via `is_pure_hex` (not `is_allowlisted`
        // because hex is now context-dependent; this tests the primitive directly).
        let sha = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
        assert!(is_pure_hex(sha));
    }

    #[test]
    fn allowlist_passes_uuid_canonical() {
        assert!(is_uuid_canonical("550e8400-e29b-41d4-a716-446655440000"));
    }

    #[test]
    fn allowlist_does_not_pass_mixed_token() {
        // A token that starts with letters but mixes in non-hex chars.
        assert!(!is_pure_hex("sk-aaaaaabbbbbbccccccddddddeeeeeeffffgg"));
    }

    // ── Structured-field gate helpers ────────────────────────────────────────

    #[test]
    fn check_json_blocks_secret_in_object_value() {
        let props = serde_json::json!({ "api_key": "AKIAFAKEKEY1234567890" });
        assert!(
            check_json(&props).is_err(),
            "secret in properties object value must be blocked"
        );
    }

    #[test]
    fn check_json_blocks_secret_in_nested_object() {
        let props = serde_json::json!({
            "credentials": { "token": openai_project_key_fixture() }
        });
        assert!(
            check_json(&props).is_err(),
            "secret in nested properties object must be blocked"
        );
    }

    #[test]
    fn check_json_blocks_secret_in_array() {
        let props = serde_json::json!(["normal", "AKIAFAKEKEY1234567890"]);
        assert!(
            check_json(&props).is_err(),
            "secret in JSON array must be blocked"
        );
    }

    // ── Reserved secret-gate property key (ADR-115 Amendment 1) ─────────────

    #[test]
    fn reject_reserved_key_passes_absent_properties() {
        assert!(reject_reserved_secret_gate_property(None).is_ok());
    }

    #[test]
    fn reject_reserved_key_passes_unrelated_properties() {
        let props = serde_json::json!({"name": "value", "tags": ["a", "b"]});
        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
    }

    #[test]
    fn reject_reserved_key_passes_non_object_properties() {
        // Non-object properties cannot name a top-level key at all.
        let props = serde_json::json!("just a string");
        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
        let arr = serde_json::json!(["a", "b"]);
        assert!(reject_reserved_secret_gate_property(Some(&arr)).is_ok());
    }

    #[test]
    fn reject_reserved_key_blocks_top_level_key_creation() {
        let props = serde_json::json!({"khive:secret_gate": "exempted:content-sha256-manifest-v1"});
        let err = reject_reserved_secret_gate_property(Some(&props)).unwrap_err();
        assert!(
            matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("khive:secret_gate") && msg.contains("runtime-owned")),
            "unexpected error: {err:?}"
        );
    }

    #[test]
    fn reject_reserved_key_blocks_regardless_of_value_shape() {
        // Presence alone is rejected — arbitrary value, null (explicit removal
        // shape), and a value that happens to match the real stamp format are
        // all rejected identically; a caller can never legitimately write this
        // key by any value.
        for value in [
            serde_json::json!(null),
            serde_json::json!(42),
            serde_json::json!({"nested": "object"}),
            serde_json::json!("exempted:content-sha256-manifest-v1"),
        ] {
            let props = serde_json::json!({"khive:secret_gate": value});
            assert!(
                reject_reserved_secret_gate_property(Some(&props)).is_err(),
                "must reject value shape: {props:?}"
            );
        }
    }

    #[test]
    fn reject_reserved_key_allows_nested_non_top_level_occurrence() {
        // The same spelling nested inside a value is ordinary content, not a
        // posture mutation — only the exact top-level key is reserved.
        let props = serde_json::json!({"notes": {"khive:secret_gate": "not-a-stamp"}});
        assert!(reject_reserved_secret_gate_property(Some(&props)).is_ok());
    }

    #[test]
    fn reject_reserved_key_blocks_alongside_other_legitimate_keys() {
        let props = serde_json::json!({
            "name": "value",
            "khive:secret_gate": "exempted:content-sha256-manifest-v1",
        });
        assert!(reject_reserved_secret_gate_property(Some(&props)).is_err());
    }

    #[test]
    fn check_json_passes_safe_properties() {
        let props = serde_json::json!({
            "domain": "attention",
            "status": "researched",
            "year": 2024
        });
        assert!(
            check_json(&props).is_ok(),
            "normal properties must pass; fired: {:?}",
            check_json(&props).err()
        );
    }

    #[test]
    fn check_tags_blocks_credential_tag() {
        let tags = vec![
            "type:concept".to_string(),
            "AKIAFAKEKEY1234567890".to_string(),
        ];
        assert!(
            check_tags(&tags).is_err(),
            "credential-shaped tag must be blocked"
        );
    }

    #[test]
    fn check_tags_passes_normal_tags() {
        let tags = vec!["type:concept".to_string(), "domain:attention".to_string()];
        assert!(
            check_tags(&tags).is_ok(),
            "normal tags must pass; fired: {:?}",
            check_tags(&tags).err()
        );
    }

    // ── False-positive: sk-learn and scikit-learn slugs ──────────────────────

    #[test]
    fn allows_sk_learn_prose() {
        // scikit-learn slug used as an entity name or knowledge atom.
        let texts = &[
            "sk-learn is a Python machine learning library",
            "sk-learn-compatible transformer pipeline reference",
            "sk-learn scikit-learn estimator interface",
        ];
        for t in texts {
            assert!(
                scan(t).is_none(),
                "sk-learn prose must pass; fired: {:?} on {:?}",
                scan(t),
                t
            );
        }
    }

    #[test]
    fn blocks_openai_sk_proj_not_confused_with_sk_learn() {
        // Real OpenAI key shape must still be caught.
        let fake = openai_project_key_fixture();
        assert!(
            scan(&fake).is_some(),
            "sk-proj- key must still be caught after sk-learn exemption"
        );
    }

    // ── False-positive: SRI / tokenizer hash metadata ────────────────────────

    #[test]
    fn blocks_sri_hash_near_key_word_accepted_fp() {
        // SRI hash as used in HTML integrity attributes (sha384, base64-encoded),
        // placed directly beside the trigger word "key". The content-hash
        // allowlist is a prose-context exemption, not unconditional: near a
        // credential trigger, a sha-prefixed hash falls through to the explicit
        // near-trigger content-hash detector like any other high-entropy
        // candidate. This is an accepted false positive on a real but rare
        // shape (an integrity hash literally next to the word "key").
        let line = "integrity key: sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC";
        assert!(
            scan(line).is_some(),
            "SRI hash near trigger word 'key' must now be blocked (accepted FP); passed unexpectedly"
        );
    }

    #[test]
    fn allows_base64_tokenizer_hash_metadata() {
        // Tokenizer metadata containing a base64 hash near technical keywords.
        let line = "tokenizer_vocab_hash: Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
        assert!(
            scan(line).is_none(),
            "tokenizer hash metadata must pass; fired: {:?}",
            scan(line)
        );
    }

    #[test]
    fn allows_npm_lockfile_integrity() {
        // npm lockfile integrity line with sha512 base64url hash (86 base64 chars + ==).
        // sha512 digest = 64 bytes → base64 = 88 chars (86 unpadded + ==).
        let body_86 = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1234567890abcdefghijklmnopqrstuvwxABCDEFGHIJKLMNOPQRST";
        assert_eq!(body_86.len(), 86, "test body must be exactly 86 chars");
        let line = format!(
            "resolved: https://registry.npmjs.org/foo/-/foo-1.0.0.tgz\nintegrity: sha512-{body_86}=="
        );
        assert!(
            scan(&line).is_none(),
            "npm lockfile integrity must pass; fired: {:?}",
            scan(&line)
        );
    }

    // ── False-positive: tokenizer vs token trigger word ─────────────────────

    #[test]
    fn allows_tokenizer_vocab_hash_no_block() {
        // `tokenizer_vocab_hash` contains the substring "token" but NOT as a
        // standalone word (followed by 'i' which is alphanumeric), so the
        // standalone-token boundary check must not fire here.
        let line = "tokenizer_vocab_hash = Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow
        assert!(
            scan(line).is_none(),
            "tokenizer_vocab_hash must pass; 'token' is only standalone-word matched; fired: {:?}",
            scan(line)
        );
    }

    // ── True-positives: bare base64 at sha-lengths near trigger words ────────

    #[test]
    fn blocks_bare_base64url_43chars_near_key() {
        // A 43-char base64url token (= sha256 body length) near the word "key".
        // Without a sha<N>- prefix this MUST be caught, not allowlisted.
        let token_43 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123"; // gitleaks:allow
        assert_eq!(token_43.len(), 43, "test token must be exactly 43 chars");
        let line = format!("api key {token_43}");
        assert!(
            scan(&line).is_some(),
            "43-char base64url token near 'key' must be caught (no sha-prefix = not a hash); fired: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn blocks_bare_base64url_64chars_near_secret() {
        // A 64-char base64url token (= sha384 body length) near "secret".
        // Must be caught without sha<N>- prefix.
        let token_64 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123wJalrXUtnFEMI-K7MDENa"; // gitleaks:allow
        assert_eq!(token_64.len(), 64, "test token must be exactly 64 chars");
        let line = format!("secret: {token_64}");
        assert!(
            scan(&line).is_some(),
            "64-char base64url token near 'secret' must be caught; got: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn blocks_bare_base64url_86chars_near_auth() {
        // An 86-char base64url token (= sha512 body length) near "auth".
        // Must be caught without sha<N>- prefix.
        let token_86 = "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123wJalrXUtnFEMI-K7MDENwJalrXUtnFEMI-K7MDENabc"; // gitleaks:allow
        assert_eq!(token_86.len(), 86, "test token must be exactly 86 chars");
        let line = format!("auth header {token_86}");
        assert!(
            scan(&line).is_some(),
            "86-char base64url token near 'auth' must be caught; got: {:?}",
            scan(&line)
        );
    }

    // ── True-positives: standalone `token` trigger ───────────────────────────

    #[test]
    fn blocks_service_token_opaque_value() {
        // "service token <opaque-high-entropy>" — `token` as a standalone word
        // with a high-entropy value must be caught.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        assert!(
            opaque.len() >= 24,
            "opaque must be long enough for entropy check"
        );
        let line = format!("service token {opaque}");
        assert!(
            scan(&line).is_some(),
            "service token <opaque> must be caught by standalone 'token' check; got: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn blocks_token_equals_credential() {
        // `token=<high-entropy>` (assignment form) must be caught via has_token_assignment.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let line = format!("token={opaque}");
        assert!(
            scan(&line).is_some(),
            "token=<value> must be caught via token= trigger; got: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn blocks_token_colon_credential() {
        // `token: <high-entropy>` (key-value form) must be caught via has_token_assignment.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let line = format!("token: {opaque}");
        assert!(
            scan(&line).is_some(),
            "token: <value> must be caught via token: trigger; got: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn allows_next_token_technical_context() {
        // `next_token` is a technical term; the high-entropy value here has low
        // entropy anyway, so it must pass.
        let line = "next_token: cursor-page-2-abcdef12345678";
        assert!(
            scan(line).is_none(),
            "next_token technical context must not be blocked; fired: {:?}",
            scan(line)
        );
    }

    // ── Boundary-aware token= / token: (compound identifiers must pass) ─────

    #[test]
    fn allows_next_token_high_entropy_cursor() {
        // `next_token:` with a realistic high-entropy pagination cursor must NOT be
        // blocked.  `next_token` has `_token` suffix — not a standalone assignment form.
        let cursor = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let line = format!("next_token: {cursor}");
        assert!(
            scan(&line).is_none(),
            "next_token with high-entropy cursor must pass (compound identifier); fired: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn allows_token_count_high_entropy() {
        // `token_count:` with a high-entropy value must NOT be blocked.
        // `token_count` has `token_` prefix — the word boundary after `token` is `_`,
        // which is excluded by has_token_assignment.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let line = format!("token_count: {opaque}");
        assert!(
            scan(&line).is_none(),
            "token_count with high-entropy value must pass; fired: {:?}",
            scan(&line)
        );
    }

    // ── Hex allowlist is not applied when trigger context is present ────────
    // Pure hex tops out at log2(16) = 4.0 bits/char, below ENTROPY_THRESHOLD (4.5), so
    // the entropy heuristic alone never flags it. The hex allowlist must only apply
    // when NOT near a trigger; the tests below guard that ordering.

    #[test]
    fn hex_near_key_blocked_in_credential_context() {
        // A pure-hex 32-char token near "api key" is a credential-shaped hex
        // token in trigger context.  Entropy alone cannot flag it (hex max =
        // 4.0 < 4.5 threshold), but the explicit hex-credential-token path
        // must catch it.
        let hex32 = "4f9c2e8a1d3b5c7e9f0a2b4d6e8c0a2b";
        assert_eq!(hex32.len(), 32);
        let line = format!("api key {hex32}");
        assert!(
            scan(&line).is_some(),
            "32-char pure hex near 'api key' must be blocked; got None"
        );
    }

    #[test]
    fn issue_2056_hex_bridge_masks_the_matched_candidate() {
        let hex32 = "0af7651916cd43dd8448eb211c80319c";
        let content = format!("api key values verbatim:\n  {hex32}");

        let (candidate, detector) = scan_match(&content).expect("credential must have a span");
        assert_eq!(detector, "hex-credential-token");
        assert_eq!(candidate, hex32);
        assert!(candidate.bytes().all(|byte| byte.is_ascii_hexdigit()));

        let matched = scan(&content).expect("credential-labeled hex must be blocked");
        assert_eq!(matched.detector, "hex-credential-token");
        assert_eq!(matched.masked, "0af765...32chars");
    }

    #[test]
    fn issue_2056_detector_name_does_not_trigger_across_sentence_boundary() {
        let content = "The hex-credential-token bucket held 18. Six are two values verbatim:\n\
                       0af7651916cd43dd8448eb211c80319c -- spec example identifier";

        assert!(
            check(content).is_ok(),
            "a detector name in an earlier sentence must not trigger: {:?}",
            scan(content)
        );
    }

    #[test]
    fn issue_2076_allows_repository_revision_links_near_prose_triggers() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let contents = [
            format!(
                "key-scoped source citation: \
                 https://github.com/acme/widgets/blob/{revision}/src/runtime/mod.rs"
            ),
            format!("auth-bound rendering keeps <a href=\"{revision}\">the commit link</a> intact"),
        ];

        for content in contents {
            assert!(
                check(&content).is_ok(),
                "repository revision reference must pass: {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn issue_2076_repository_revision_links_do_not_hide_labeled_secrets() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let contents = [
            format!("api key: https://github.com/acme/widgets/blob/{revision}/src/runtime/mod.rs"),
            format!("secret key: href=\"{revision}\""),
        ];

        for content in contents {
            assert!(
                check(&content).is_err(),
                "a direct credential label must still block: {content:?}"
            );
        }
    }

    #[test]
    fn issue_2076_guidance_names_a_boundary_that_changes_the_predicate() {
        let guidance = block_guidance("high-entropy-token");
        assert!(guidance.contains("sentence") || guidance.contains("paragraph"));
        assert!(
            !guidance.contains("own line"),
            "a single newline remains inside the trigger window"
        );
    }

    #[test]
    fn issue_1988_allows_dense_latex_fragments_near_math_vocabulary() {
        let latex = r"\operatorname{Spec}_{H_0^1(\Omega)}(K_N(\tau_{\omega}))^{1/2}";
        assert!(latex.len() >= MIN_ENTROPY_LEN);
        assert!(shannon_entropy(latex.as_bytes()) >= ENTROPY_THRESHOLD);
        let content = format!("the attention key estimate uses {latex}");

        assert!(
            check(&content).is_ok(),
            "LaTeX structure must not be mistaken for a credential: {:?}",
            scan(&content)
        );
    }

    #[test]
    fn issue_1988_latex_exemption_does_not_hide_credential_runs() {
        let credential = "a3f5c2e9d1b8047e63a1f4c2d5b6e8f1a9c3d2e4"; // gitleaks:allow
        let content = format!(r"api key: \texttt{{{credential}}}");

        assert!(
            check(&content).is_err(),
            "credential-shaped runs inside LaTeX must remain blocked"
        );
    }

    #[test]
    fn issue_1988_published_secret_vectors_remain_fail_closed() {
        // RFC 8032 Ed25519ph example secret. Published status cannot be
        // inferred from shape, so exact vectors remain blocked unless a
        // caller uses the separately audited exemption contract.
        let published = "833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42";
        let content = format!("RFC 8032 secret key test vector: {published}");

        assert!(check(&content).is_err());
    }

    #[test]
    fn hex_credential_lengths_blocked_near_trigger() {
        // Verify all four credential-shaped lengths are caught near a trigger.
        let hex40 = "a3f5c2e9d1b8047e63a1f4c2d5b6e8f1a9c3d2e4";
        let hex64 = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b";
        let hex128 = format!("{hex64}{hex64}");
        assert_eq!(hex40.len(), 40);
        assert_eq!(hex64.len(), 64);
        assert_eq!(hex128.len(), 128);

        for (label, hex) in &[
            ("hex40", hex40),
            ("hex64", hex64),
            ("hex128", hex128.as_str()),
        ] {
            let line = format!("secret key: {hex}");
            assert!(
                scan(&line).is_some(),
                "{label} near 'secret key' must be blocked; got None"
            );
        }
    }

    #[test]
    fn hex_blocked_when_trigger_and_hash_word_coexist() {
        // Credential trigger dominates: adding "hash" or "sha" to the window does
        // not rescue a pure-hex token when a credential trigger is also present.
        // An attacker controlling the prose could otherwise bypass the gate with
        // one extra word, so the hash-word exception must NOT apply in trigger context.
        let hex32 = "4f9c2e8a1d3b5c7e9f0a2b4d6e8c0a2b";
        let key_hash_line = format!("api key hash {hex32}");
        let secret_sha_line = format!("secret sha {hex32}");
        assert!(
            scan(&key_hash_line).is_some(),
            "'api key hash <hex32>' must be blocked; got None"
        );
        assert!(
            scan(&secret_sha_line).is_some(),
            "'secret sha <hex32>' must be blocked; got None"
        );
    }

    #[test]
    fn hex_near_sha_context_word_allowed() {
        // A 40-char hex with "sha" or "commit" in the window — but no credential
        // trigger — must be allowed (git SHA or content hash in normal prose).
        let hex40 = "da39a3ee5e6b4b0d3255bfef95601890afd80709";
        let sha_line = format!("sha1: {hex40}");
        let commit_line = format!("commit sha {hex40}");
        assert!(
            scan(&sha_line).is_none(),
            "hex40 near 'sha1' context must be allowed; fired: {:?}",
            scan(&sha_line)
        );
        assert!(
            scan(&commit_line).is_none(),
            "hex40 near 'commit sha' context must be allowed; fired: {:?}",
            scan(&commit_line)
        );
    }

    const GIT_LENGTH_FIXTURE: &str = "da39a3ee5e6b4b0d3255bfef95601890afd80709";

    #[test]
    fn bare_forty_hex_line_three_allows_trigger_on_line_one_within_window() {
        let content = format!("auth changes\nready\n{GIT_LENGTH_FIXTURE}");
        assert!(content.len() < TRIGGER_WINDOW);
        assert!(check(&content).is_ok());
        assert_eq!(mask_secrets(&content), content);
    }

    #[test]
    fn bare_forty_hex_line_three_allows_trigger_beyond_window() {
        let content = format!("auth changes\n{}\n{GIT_LENGTH_FIXTURE}", "-".repeat(150));
        assert!(check(&content).is_ok());
    }

    #[test]
    fn forty_hex_allows_direct_sha_or_commit_marker_in_prose() {
        for marker in ["sha:", "commit"] {
            let content = format!("auth changes\nready\n{marker} {GIT_LENGTH_FIXTURE}");
            assert!(check(&content).is_ok(), "{marker}");
        }
    }

    #[test]
    fn forty_hex_refuses_same_line_token_assignment() {
        let content = format!("token: {GIT_LENGTH_FIXTURE}");
        let matched = scan(&content).expect("explicit credential assignment");
        assert_eq!(matched.detector, "hex-credential-token");
        assert_eq!(matched.trigger, Some("token"));
        assert!(check(&content).is_err());
        assert!(!mask_secrets(&content).contains(GIT_LENGTH_FIXTURE));
    }

    #[test]
    fn forty_hex_refuses_previous_label_line_ending_colon_or_equals() {
        for newline in ["\n", "\r\n", "\r"] {
            for delimiter in [":", "="] {
                let content = format!("token{delimiter}{newline}  `{GIT_LENGTH_FIXTURE}`");
                let matched = scan(&content).expect("previous line labels the value");
                assert_eq!(matched.detector, "hex-credential-token");
                assert_eq!(matched.trigger, Some("token"));
                assert!(!mask_secrets(&content).contains(GIT_LENGTH_FIXTURE));
            }
        }
    }

    #[test]
    fn forty_hex_context_stays_on_line_except_immediate_assignment_label() {
        for content in [
            format!("token\n{GIT_LENGTH_FIXTURE}"),
            format!("token:\n\n{GIT_LENGTH_FIXTURE}"),
            format!("{GIT_LENGTH_FIXTURE}\nauth changes"),
            format!("token_count:\n{GIT_LENGTH_FIXTURE}"),
            format!("authorized:\n{GIT_LENGTH_FIXTURE}"),
            format!("{}\n{GIT_LENGTH_FIXTURE}\n密钥", "文".repeat(80)),
        ] {
            assert!(check(&content).is_ok(), "{content}");
        }
        for content in [
            format!("{GIT_LENGTH_FIXTURE} auth"),
            format!("api_keyv2 =\n{GIT_LENGTH_FIXTURE}"),
            format!("secret for deploy: \n{GIT_LENGTH_FIXTURE}"),
        ] {
            assert!(check(&content).is_err(), "{content}");
        }
    }

    #[test]
    fn other_hex_lengths_still_refuse_cross_line_trigger_context() {
        for length in [32, 64, 128] {
            let value = "a".repeat(length);
            let content = format!("auth changes\nready\n{value}");
            let matched = scan(&content).expect("unchanged cross-line context");
            assert_eq!(matched.detector, "hex-credential-token");
            assert_eq!(matched.trigger, Some("auth"));
        }
    }

    #[test]
    fn prefixed_hex_of_forty_bytes_keeps_cross_line_trigger_context() {
        for prefix in ["0x", "0X"] {
            let value = format!("{prefix}{}", "a".repeat(38));
            let content = format!("auth changes\nready\n{value}");
            assert!(check(&content).is_err());
            assert!(!mask_secrets(&content).contains(&value));
        }
    }

    #[test]
    fn forty_hex_beside_bridgeable_prose_keeps_conservative_trigger_context() {
        let content = format!("auth changes\ncompleted\n{GIT_LENGTH_FIXTURE}");
        assert!(check(&content).is_err());
        assert!(!mask_secrets(&content).contains(GIT_LENGTH_FIXTURE));
    }

    #[test]
    fn forty_hex_bridge_fragments_keep_cross_line_detection_and_full_masking() {
        for lengths in [(40, 24), (24, 40), (40, 40)] {
            let first = "a".repeat(lengths.0);
            let second = "b".repeat(lengths.1);
            let content = format!("auth changes\nready\n{first}\u{200B}{second}");
            let matched = scan(&content).expect("fragment keeps original trigger context");
            assert_eq!(matched.detector, "hex-credential-token");
            assert_eq!(matched.trigger, Some("auth"));
            let masked = mask_secrets(&content);
            assert!(!masked.contains(&first), "first fragment remains");
            assert!(!masked.contains(&second), "second fragment remains");
            assert_eq!(
                masked,
                "auth changes\nready\n***MASKED***\u{200B}***MASKED***"
            );
        }
    }

    #[test]
    fn refusal_names_rule_and_canonical_trigger_without_candidate_text() {
        for (label, trigger) in [
            ("token", "token"),
            ("AUTH", "auth"),
            ("api_keyv2", "api_key"),
        ] {
            let content = format!("{label}: {GIT_LENGTH_FIXTURE}");
            let error = check(&content).unwrap_err().to_string();
            assert!(error.contains("hex-credential-token"));
            assert!(error.contains(&format!("near '{trigger}'")), "{error}");
            assert!(!error.contains(&GIT_LENGTH_FIXTURE[..6]));
        }
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let error = check(&format!("secret: {opaque}")).unwrap_err().to_string();
        assert!(error.contains("high-entropy-token near 'secret'"));
        assert!(!error.contains(&opaque[..6]));
        let provider = "AKIAFAKEKEY1234567890";
        let matched = scan(provider).unwrap();
        assert_eq!(matched.trigger, None);
        assert!(!matched.to_string().contains(&provider[..6]));
    }

    #[test]
    fn allows_git_revision_reference_near_ordinary_key_and_token_prose() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let contents = [
            format!("the primary key behavior is pinned to commit {revision}"),
            format!("revision: {revision} emits one extra token"),
            format!("primary key behavior at revision:{revision};"),
            format!("configuration key\n\nrev {revision}."),
            format!("one extra token was introduced by sha: {revision}"),
        ];
        for content in &contents {
            assert!(
                check(content).is_ok(),
                "git revision reference in technical prose must pass: {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn git_revision_reference_does_not_exempt_credential_assignments() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("api_key={revision}"),
            format!("secret key: {revision}"),
            format!("token={revision}"),
            format!("api key hash {revision}"),
        ] {
            assert!(
                check(&content).is_err(),
                "credential assignment must remain blocked: {content:?}"
            );
        }
    }

    #[test]
    fn blocks_forty_hex_after_credential_phrase_with_vcs_marker() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("api key value is commit {revision}"),
            format!("api key value is revision {revision}"),
            format!("the secret is rev {revision}"),
            format!("token value sha {revision}"),
        ] {
            assert_eq!(
                scan(&content).map(|matched| matched.detector),
                Some("hex-credential-token"),
                "a credential phrase must not be hidden by connector words before \
                 a VCS marker: {content:?}"
            );
        }
    }

    #[test]
    fn blocks_unicode_punctuation_between_vcs_marker_and_forty_hex() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("api_key value commit\u{200B}{revision}");
        assert!(
            check(&content).is_err(),
            "a zero-width space between marker and value must not rescue a \
             labeled credential: {content:?}, got {:?}",
            scan(&content)
        );
    }

    #[test]
    fn blocks_slash_bearing_base64_credential_in_value_syntax() {
        // 40-char standard-base64-alphabet value whose `/` splits it into two
        // runs (19 and 20 bytes) each below MIN_ENTROPY_LEN — per-run checks
        // never see it, so the block must come from refusing the path
        // exemption for a credential-value clause and applying whole-token
        // entropy.
        let content = "api key value is Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "slash-bearing base64 credential in value syntax must be blocked"
        );
    }

    #[test]
    fn blocks_angle_bracket_line_range_base64_credential_in_value_syntax() {
        let content = "api key value is <Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh>:~97-103";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "angle-bracket/line-range dressing must not exempt a credential in \
             value syntax"
        );
    }

    #[test]
    fn blocks_split_hex_credential_with_marker_adjacent_fragment() {
        // A 64-hex credential split 40+24 by a zero-width space, with the
        // first fragment hiding behind a VCS marker. The marker-adjacent
        // fragment is exempt as its own anchor, but the second fragment
        // anchors its own reconstruction chain, walks back across the gap,
        // and accumulates 40+24=64 — the symmetric-anchor property the
        // vcs-exempt bridge skip relies on.
        let content = concat!(
            "api token context: commit ",
            "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf",
            "\u{200B}",
            "0123456789abcdef01234567"
        );
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("hex-credential-token"),
            "split credential with a marker-adjacent fragment must be blocked"
        );
    }

    #[test]
    fn blocks_forty_hex_behind_qualified_label_with_delimiter() {
        // A label with qualifier words the connector set cannot enumerate
        // ("for deploy") followed by a value delimiter is assignment syntax:
        // once the walk crosses the `:`/`=`, every label-side identifier is
        // stepped over until the trigger word.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("api key for deploy: commit {revision}"),
            format!("prod api key for deploy = commit {revision}"),
        ] {
            assert_eq!(
                scan(&content).map(|matched| matched.detector),
                Some("hex-credential-token"),
                "a qualified label before a value delimiter must not be \
                 hidden from the exemption guard: {content:?}"
            );
        }
    }

    #[test]
    fn blocks_slash_base64_behind_qualified_label_with_delimiter() {
        let content = "api key for deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "a qualified label before a value delimiter must refuse the path \
             exemption for a slash-bearing base64 credential"
        );
    }

    #[test]
    fn blocks_forty_hex_behind_versioned_label() {
        // `v1.2` splits into version fragments under identifier extraction;
        // the intra-token dot must not read as a sentence boundary and the
        // fragments must be stepped over like connector words.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("api key v1.2 value is commit {revision}");
        assert_eq!(
            scan(&content).map(|matched| matched.detector),
            Some("hex-credential-token"),
            "a versioned credential label must stay reachable through its \
             version fragments: {content:?}"
        );
    }

    #[test]
    fn blocks_labeled_inline_marker_split_credential() {
        // The r2 medium probes: `marker:value` inline forms carrying a split
        // credential, with a credential label ahead of a value delimiter.
        // The clause guard disables the VCS exemption, and whole-token
        // normalized-hex accumulation fires on the fused token.
        for content in [
            concat!(
                "api token context: rev:",
                "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf",
                "\u{200B}",
                "0123456789abcdef01234567"
            )
            .to_string(),
            concat!(
                "api token context: ",
                "0123456789abcdef01234567",
                "\u{200B}",
                "rev:d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf"
            )
            .to_string(),
        ] {
            assert!(
                check(&content).is_err(),
                "a labeled inline-marker split credential must be blocked: \
                 {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn blocks_forty_hex_behind_multiword_label_and_marker_delimiter() {
        // Coverage: qualifier nouns beyond the two-word case are
        // reachable once prepositions/possessives read as glue, and a
        // delimiter attached to the VCS marker itself ("deploy sha: <hex>")
        // is assignment syntax like any other delimiter.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("api key for deploy sha: {revision}"),
            format!("prod api key for deploy sha: {revision}"),
            format!("api key for production deploy: commit {revision}"),
        ] {
            assert_eq!(
                scan(&content).map(|matched| matched.detector),
                Some("hex-credential-token"),
                "a natural multiword credential label must not be hidden by \
                 glue words or a marker-attached delimiter: {content:?}"
            );
        }
    }

    #[test]
    fn blocks_slash_base64_behind_possessive_qualified_label() {
        let content = "api key for our production deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "possessive-qualified credential label must refuse the path \
             exemption"
        );
    }

    #[test]
    fn blocks_forty_hex_behind_participial_adjective_qualifier() {
        // Coverage: a past-participle word in ADJECTIVE position
        // (followed by a content noun: "shared deploy", "encrypted backup")
        // is a label qualifier, not verb-phrase prose, and must not end the
        // walk.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("api key for shared deploy: commit {revision}");
        assert_eq!(
            scan(&content).map(|matched| matched.detector),
            Some("hex-credential-token"),
            "a participial-adjective label qualifier must stay walkable: \
             {content:?}"
        );
    }

    #[test]
    fn blocks_slash_base64_behind_participial_adjective_qualifier() {
        let content = "api key for encrypted backup: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "a participial-adjective label qualifier must refuse the path \
             exemption"
        );
    }

    #[test]
    fn blocks_forty_hex_behind_chained_qualifier_label() {
        // Coverage: a chain of qualifiers between the value and
        // the trigger ("shared encrypted deploy") must not exhaust the walk
        // before the label head is reached. Any per-clause content-word cap
        // re-admits this bypass one qualifier past the cap.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("api key for shared encrypted deploy: commit {revision}");
        assert_eq!(
            scan(&content).map(|matched| matched.detector),
            Some("hex-credential-token"),
            "a chained-qualifier credential label must stay walkable: \
             {content:?}"
        );
    }

    #[test]
    fn blocks_slash_base64_behind_chained_qualifier_label() {
        let content =
            "api key for shared encrypted deploy: Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "a chained-qualifier credential label must refuse the path \
             exemption"
        );
    }

    #[test]
    fn blocks_over_limit_qualified_label_fails_closed() {
        // Coverage: labels whose clause exhausts the walk budget
        // (a marker, an extra qualifier, or an interleaved glue word pushes
        // the trigger past the limit). Exhaustion after a value delimiter
        // fails closed — clause length must not launder a labeled credential
        // into the exemptions.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let opaque = "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        for content in [
            format!("api key for the new shared encrypted staging deploy: commit {revision}"),
            format!("api key for the new shared encrypted regional staging deploy: {opaque}"),
            format!("api key for the new shared and encrypted staging deploy: {opaque}"),
            format!(
                "api key for the new shared encrypted regional staging deploy: commit {revision}"
            ),
            format!("api key for the new shared and encrypted staging deploy: commit {revision}"),
            format!("api key for the new shared encrypted staging deploy: {opaque}"),
        ] {
            assert!(
                check(&content).is_err(),
                "an over-limit qualified credential label must fail closed: \
                 {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn accepted_false_positive_topical_trigger_before_delimited_path() {
        // The clause walk treats ANY reachable pre-delimiter trigger as a
        // credential label — it has no grammar to tell a label head ("api
        // key ...") from a topical object ("testing auth against parser").
        // Distinguishing them would reopen the labeled-value bypasses, so
        // this ordinary prose shape blocks. Accepted false positive,
        // conservative direction; documented in docs/api/secret_gate.md.
        let content = "results from testing auth against parser: \
             internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
        assert!(
            check(content).is_err(),
            "accepted-FP contract changed: topical trigger before a \
             delimited path no longer blocks — update the docs if deliberate"
        );
    }

    #[test]
    fn blocks_participle_before_trigger_word() {
        // Ordering contract: a past-participle word BEFORE the trigger never
        // matters — the walk reaches the trigger first. Pinned so the
        // verb-position rule cannot regress into shielding these labels.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let opaque = "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh";
        for content in [
            format!("shared key: {revision}"),
            format!("generated api key: {revision}"),
            format!("encrypted token = {opaque}"),
        ] {
            assert!(
                check(&content).is_err(),
                "a participle before the trigger word must not shield the \
                 label: {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn accepted_false_positive_docs_path_behind_attributive_trigger_and_delimiter() {
        // "auth setup: <path>" carries a trigger word in clause range ahead
        // of a value delimiter; the walk cannot distinguish an attributive
        // trigger ("auth setup") from a label head ("api key ...") without
        // reopening the labeled-value bypasses, so this ordinary prose shape
        // blocks. Accepted false positive — conservative direction under the
        // threat model; documented in docs/api/secret_gate.md.
        let content = "see the docs for auth setup: \
             internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
        assert!(
            check(content).is_err(),
            "accepted-FP contract changed: attributive trigger before a \
             delimited path no longer blocks — update the docs if deliberate"
        );
    }

    #[test]
    fn allows_verb_phrase_prose_with_delimiter_before_trigger_word() {
        // Past-participle content words are verb-phrase evidence: the clause
        // narrates an action on the value instead of labeling it. These are
        // the false-positive shapes the exemptions exist for, and they must
        // survive the marker-attached-delimiter and glue-word widenings.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("one extra token was introduced by sha: {revision}"),
            format!("the api key was rotated. deploy notes reference commit {revision}"),
            format!("api key updated: commit {revision}"),
        ] {
            assert!(
                check(&content).is_ok(),
                "verb-phrase prose must keep the VCS exemption: {content:?}, \
                 got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn allows_unlabeled_unknown_connector_without_delimiter() {
        // VCS coordinates retain the strict no-delimiter tier: an identifier
        // outside the connector set ends the walk. The bounded bridge used by
        // file paths must not re-block this ordinary revision prose.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("the key changes are in commit {revision}"),
            format!("deployed at commit {revision}"),
        ] {
            assert!(
                check(&content).is_ok(),
                "prose without a value delimiter must keep the VCS exemption: \
                 {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn blocks_direct_no_delimiter_labels_for_both_file_path_value_families() {
        let values = [
            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
        ];

        for value in values {
            for label in ["api key found", "auth scanner found", "secret note"] {
                let content = format!("{label} {value}");
                assert!(
                    check(&content).is_err(),
                    "a direct no-delimiter label must refuse the file-path exemption: \
                     {content:?}, got {:?}",
                    scan(&content)
                );
            }
        }
    }

    #[test]
    fn blocks_direct_gerund_and_see_labels_for_both_file_path_value_families() {
        let values = [
            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
        ];

        for value in values {
            for label in [
                "api key handling",
                "auth scanner handling",
                "api key see",
                "key: see",
            ] {
                let content = format!("{label} {value}");
                assert!(
                    check(&content).is_err(),
                    "narrative-looking adjacency must not shield a direct credential label: \
                     {content:?}, got {:?}",
                    scan(&content)
                );
            }
        }
    }

    #[test]
    fn blocks_direct_participle_labels_for_both_file_path_value_families() {
        let values = [
            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
        ];

        for value in values {
            for label in ["api key leaked", "auth scanner leaked"] {
                let content = format!("{label} {value}");
                assert!(
                    check(&content).is_err(),
                    "step-zero participle adjacency must not shield a direct credential label: \
                     {content:?}, got {:?}",
                    scan(&content)
                );
            }
        }
    }

    #[test]
    fn allows_no_delimiter_narrative_file_path_prose() {
        // The value-side `file`/`this` identifiers provide real walk context
        // before `flagged`; the step-zero direct-label tightening must not
        // remove this required narrative exemption.
        let content = "the auth scanner flagged this file \
            internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";

        assert!(
            check(content).is_ok(),
            "a regular participle in narrative position must preserve the path: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn suffix_word_hundred_is_not_a_narrative_participle() {
        assert!(is_clause_narrative_participle("flagged"));
        assert!(is_clause_narrative_participle("INTRODUCED"));
        assert!(!is_clause_narrative_participle("found"));
        assert!(!is_clause_narrative_participle("hundred"));
        assert!(is_clause_narrative_gerund("HANDLING"));
        assert!(!is_clause_narrative_gerund("found"));

        for value in [
            "Xk9mZ2vQpLrT8nJwYuA/HfBsDcGiONvMabcdefgh",
            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
        ] {
            let content = format!("api key hundred: {value}");
            assert!(
                check(&content).is_err(),
                "a lexical -ed suffix must not shield a credential label: \
                 {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn allows_vcs_reference_with_prose_boundary_before_trigger_word() {
        // A sentence or paragraph boundary between a trigger word and the
        // marker/value clause means the trigger is prose context, not this
        // value's label — the clause walk must stop at the boundary.
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        for content in [
            format!("configuration key\n\nrev {revision}."),
            format!("rotate the api key. the fix is commit {revision}"),
        ] {
            assert!(
                check(&content).is_ok(),
                "boundary-separated trigger prose must not block a VCS \
                 reference: {content:?}, got {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn blocks_sha_revision_marker_immediately_labeled_as_api_key() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("api_key sha:{revision}");

        assert!(
            check(&content).is_err(),
            "credential-labeled SHA value must remain blocked: {content:?}"
        );
    }

    #[test]
    fn blocks_rev_revision_marker_immediately_labeled_as_token() {
        let revision = "d362950a3c9b1a4cb47d97f1623e38f1a1e6bcdf";
        let content = format!("token rev:{revision}");

        assert!(
            check(&content).is_err(),
            "credential-labeled revision value must remain blocked: {content:?}"
        );
    }

    #[test]
    fn hex64_near_hash_context_allowed() {
        // A 64-char hex near "sha256" or "hash" — with no credential trigger —
        // must be allowed (content digest in normal prose).
        let hex64 = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b";
        let sha_line = format!("sha256: {hex64}");
        let hash_line = format!("hash value {hex64}");
        assert!(
            scan(&sha_line).is_none(),
            "hex64 near 'sha256' must be allowed; fired: {:?}",
            scan(&sha_line)
        );
        assert!(
            scan(&hash_line).is_none(),
            "hex64 near 'hash' must be allowed; fired: {:?}",
            scan(&hash_line)
        );
    }

    #[test]
    fn blocks_high_entropy_hex_like_token_near_key() {
        // A token whose character set exceeds pure hex (contains mixed-case, digits,
        // and non-hex chars) that ALSO passes `is_pure_hex = false` AND has high
        // entropy AND appears near "key" MUST be caught.  This is the realistic
        // real-world case: hex-looking API tokens often mix case and non-hex chars.
        // Example: a 32-char mixed-charset token near "api key".
        let mixed = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"; // gitleaks:allow — not pure hex
        assert!(!is_pure_hex(mixed), "test token must not be pure hex");
        let line = format!("api key {mixed}");
        assert!(
            scan(&line).is_some(),
            "mixed-charset high-entropy token near 'api key' must be caught; got: {:?}",
            scan(&line)
        );
    }

    #[test]
    fn allows_hex40_without_trigger() {
        // 40-char hex string in a neutral context (no trigger word) must still pass —
        // it's likely a git commit SHA or content hash.
        let hex40 = "da39a3ee5e6b4b0d3255bfef95601890afd80709";
        let line = format!("commit: {hex40}");
        assert!(
            scan(&line).is_none(),
            "40-char hex without trigger word must pass; fired: {:?}",
            scan(&line)
        );
    }

    // ── check_json scans object keys ─────────────────────────────────────────

    #[test]
    fn check_json_blocks_secret_in_object_key() {
        // A credential used as a JSON object key (not a value) must be caught.
        let props = serde_json::json!({ "ghp_FakeGitHubToken0000000000000000000": "redacted" }); // gitleaks:allow
        assert!(
            check_json(&props).is_err(),
            "credential as JSON object key must be blocked"
        );
    }

    #[test]
    fn check_json_blocks_nested_secret_key() {
        // Nested credential key must be caught.
        let props = serde_json::json!({
            "metadata": {
                "AKIAFAKEKEY000000000": "value" // gitleaks:allow
            }
        });
        assert!(
            check_json(&props).is_err(),
            "nested credential as JSON object key must be blocked"
        );
    }

    // ── PEM masking format ───────────────────────────────────────────────────

    #[test]
    fn pem_masked_excerpt_reflects_block_length_not_rest_of_string() {
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let fake = format!(
            "{}\nMIIEo\u{2026}\n-----END RSA PRIVATE KEY-----\nsome trailing text that is very long",
            header
        );
        let m = scan(&fake).unwrap();
        assert_eq!(m.detector, "pem-private-key");
        // The masked length should reflect only the key block, not the whole string.
        // "some trailing text that is very long" is ~37 chars; total string is much longer.
        // The block ends after "-----END RSA PRIVATE KEY-----\n".
        // We just verify it is shorter than the full string length.
        let full_len = fake.chars().count();
        let reported_len: usize = m
            .masked
            .trim_end_matches("chars")
            .rsplit("...")
            .next()
            .and_then(|s| s.parse().ok())
            .unwrap_or(full_len + 1);
        assert!(
            reported_len < full_len,
            "masked length ({reported_len}) should be less than full string length ({full_len})"
        );
    }

    // ── UTF-8 char-boundary reproduction tests ───────────────────────────────
    //
    // These tests verify that no code path in secret_gate panics when multibyte
    // UTF-8 characters (emoji, CJK, accented Latin) appear at positions where
    // byte-level slicing could land mid-codepoint.  Each test targets a specific
    // code path.  A panic means the bug is live; a pass means the path is safe.

    /// `build_match` masked preview: if the detected candidate starts with
    /// multibyte chars the "first 6 chars" preview must not slice on a byte
    /// boundary that falls mid-codepoint.  build_match already uses
    /// `chars().take(6)`, but we exercise it with emoji-prefixed candidates.
    #[test]
    fn utf8_build_match_preview_multibyte_prefix_no_panic() {
        // "🔑" = 4 bytes; repeat 3 times = 12 bytes for only 3 chars.
        // A ghp_-prefixed token with an emoji: let's construct a scenario where
        // a known-prefix secret is immediately adjacent to multibyte content so
        // that build_match receives a slice starting at a multibyte char.
        // PEM block with multibyte chars in the body exercises build_match on a
        // candidate that may contain non-ASCII.
        let header = ["-----BEGIN RSA", " PRIVATE KEY-----"].concat(); // gitleaks:allow
        let fake = format!("{}\n🔑密钥\n-----END RSA PRIVATE KEY-----", header);
        // Must not panic; mask must not echo full body.
        let m = scan(&fake);
        assert!(m.is_some(), "PEM with emoji body must still be caught");
        let m = m.unwrap();
        assert!(
            !m.masked.contains("🔑密钥"),
            "mask must not echo the emoji body"
        );
    }

    /// `extract_token` called with a string starting with multibyte chars:
    /// the FlyV1 handler calls `extract_token(&text[payload_start..])` where
    /// `payload_start` is just past "FlyV1 " (ASCII).  If the payload is ASCII
    /// this is trivially safe, but we verify it cannot panic when the rest of
    /// the text after the payload contains multibyte chars.
    #[test]
    fn utf8_extract_token_multibyte_suffix_no_panic() {
        // "FlyV1 ABCDEFGHIJ密钥" — the payload is "ABCDEFGHIJ密钥"; extract_token
        // must stop at the ideographic chars (which are NOT ASCII whitespace) and
        // return the whole glued run without panicking.
        let text = "FlyV1 ABCDEFGHIJ密钥";
        // scan() must not panic.
        let _ = scan(text);
    }

    /// `find_prefix_token` with multibyte chars immediately before and after
    /// the known prefix: checks text[..abs] boundary slices and
    /// extract_token(&text[abs..]) do not panic.
    #[test]
    fn utf8_prefix_detector_multibyte_adjacent_no_panic() {
        // 🔑 (4 bytes) immediately before AKIA: boundary at abs = 4, which is a
        // valid char boundary (end of the emoji).  extract_token sees ASCII from abs.
        let text = "🔑AKIAFAKEKEY00000000000000";
        let _ = scan(text); // must not panic

        // é (U+00E9 = 2 bytes) immediately before ghp_:
        let text2 = "éghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
        let _ = scan(text2); // must not panic

        // Emoji immediately after the token — extract_token ends at the emoji
        // (non-whitespace, but non-ASCII acts as delimiter in entropy heuristic).
        // For prefix tokens extract_token stops at ASCII whitespace only, so the
        // emoji would be included in the token length measurement.
        let text3 = "AKIAFAKEKEY00000000000000🔑";
        let _ = scan(text3); // must not panic
    }

    /// `find_jwt` with multibyte chars as "whitespace" adjacent to a JWT-like
    /// candidate: `i = end + 1` could skip into a multibyte char if `end`
    /// pointed at a non-ASCII byte.  The position() search only looks for ASCII
    /// whitespace bytes, so a multibyte space (U+3000) is NOT found — `end`
    /// equals bytes.len() and `i = bytes.len() + 1` exits the loop.  Still
    /// verify no panic on CJK-surrounded JWT-like content.
    #[test]
    fn utf8_jwt_multibyte_adjacent_no_panic() {
        // A (fake) JWT-like triple surrounded by CJK text.
        let jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.FAKE_SIG_XXXXXXXXXXXX"; // gitleaks:allow
        let text = format!("数据{jwt}密钥");
        let _ = scan(&text); // must not panic

        // JWT followed by ideographic space (U+3000 = 3 bytes 0xE3 0x80 0x80) —
        // not matched by the ASCII-whitespace position() search.
        let text2 = format!("{jwt}\u{3000}morecontent");
        let _ = scan(&text2); // must not panic

        // JWT followed by emoji
        let text3 = format!("{jwt}🔑");
        let _ = scan(&text3); // must not panic
    }

    /// `find_url_userinfo` with multibyte chars between "://" and "@":
    /// `at_pos` from `rest.find('@')` and `colon` from `userinfo.find(':')` are
    /// ASCII markers (char boundaries), but `scheme_start` calculation uses
    /// char_indices().rev() which must handle multibyte chars in the scheme
    /// prefix correctly.
    #[test]
    fn utf8_url_userinfo_multibyte_scheme_no_panic() {
        // CJK glued to a credential URL — the scheme_start walker must not place
        // the start inside a multibyte codepoint.
        let cases = [
            "🔑postgresql://dbuser:S3cr3tP4ss@db.example.com/db", // gitleaks:allow
            "密钥mysql://root:hunter2pw@10.0.0.1:3306/app",       // gitleaks:allow
            "éredis://svc:V3ryS3cretPw@cache.internal:6379",      // gitleaks:allow
        ];
        for text in &cases {
            // Must not panic and must detect the credential.
            let result = scan(text);
            assert!(
                result.is_some(),
                "URL credential after multibyte must be caught: {text:?}"
            );
        }
    }

    /// `check_entropy_heuristic` window slicing with multibyte content at the
    /// ±TRIGGER_WINDOW boundary: `floor_char_boundary` must prevent slicing
    /// on a non-char boundary.
    #[test]
    fn utf8_entropy_window_multibyte_boundary_no_panic() {
        // Construct content where the TRIGGER_WINDOW (120 bytes) boundary falls
        // inside a 3-byte CJK character.  Repeat "数" (U+6570 = 3 bytes) to fill
        // exactly 119 bytes, then add an ASCII trigger word + high-entropy token.
        // Window start: token_offset - 120 = lands inside one of the CJK chars.
        let cjk_fill = "数".repeat(39); // 39 × 3 = 117 bytes
        assert_eq!(cjk_fill.len(), 117);
        // Pad with 2 more ASCII chars ("xy") so that the 120-byte window lands at
        // byte 119 which is the second byte of the 40th "数" — mid-multibyte.
        let secret = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
        let content = format!("{cjk_fill}xy key {secret}");
        let _ = scan(&content); // must not panic

        // Also test the right edge: token ends at byte offset, window_end =
        // token_offset + raw_token.len() + 120 may land mid-multibyte.
        let content2 = format!("key {secret}{cjk_fill}xy");
        let _ = scan(&content2); // must not panic
    }

    /// `check()` top-level fuzz: a large batch of inputs with multibyte
    /// characters at various offsets to catch any remaining panic sites.
    /// All results must be either Ok or Err (not a panic).
    #[test]
    fn utf8_no_panic_property_test() {
        let multibyte_items = [
            "🔑",       // 4-byte emoji
            "密",       // 3-byte CJK
            "é",        // 2-byte accented Latin
            "\u{3000}", // 3-byte ideographic space
            "🇺🇸",       // 8-byte emoji flag (two surrogate-like scalars)
        ];
        let secrets = [
            "AKIAFAKEKEY00000000000000".to_owned(),
            "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA".to_owned(),
            anthropic_api_key_fixture(),
            "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1".to_owned(),
            "FlyV1 fm2_AAAABBBBCCCCDDDDEEEEFFFF".to_owned(),
        ];
        for mb in &multibyte_items {
            for secret in &secrets {
                for sep in &["", " ", "\n"] {
                    // multibyte before secret
                    let s = format!("{mb}{sep}{secret}");
                    let _ = check(&s);
                    // multibyte after secret
                    let s = format!("{secret}{sep}{mb}");
                    let _ = check(&s);
                    // multibyte both sides
                    let s = format!("{mb}{sep}{secret}{sep}{mb}");
                    let _ = check(&s);
                    // repeated multibyte filling TRIGGER_WINDOW boundary
                    let fill = mb.repeat(50);
                    let s = format!("{fill} api_key {secret} {fill}");
                    let _ = check(&s);
                }
            }
        }
    }

    // ── mask_secrets: in-place redaction reusing the canonical detector ───────

    #[test]
    fn bounded_masked_log_text_masks_connection_string_credentials() {
        let raw =
            "gate backend probe failed: postgres://svc:not-a-real-secret@internal-host refused"; // gitleaks:allow
        let rendered = bounded_masked_log_text(raw);
        assert!(
            !rendered.contains("not-a-real-secret"),
            "credential must be masked: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "masked marker must record that detail was redacted: {rendered:?}"
        );
        assert!(
            rendered.contains("gate backend probe failed"),
            "non-secret diagnostic prose must survive: {rendered:?}"
        );
    }

    #[test]
    fn bounded_masked_log_text_bounds_pathological_input() {
        let raw = "x".repeat(MAX_LOG_TEXT_OUTPUT_CHARS + 500);
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            rendered.chars().count() <= MAX_LOG_TEXT_OUTPUT_CHARS + 1,
            "output must be bounded: {} chars",
            rendered.chars().count()
        );
        assert!(
            rendered.ends_with('…'),
            "truncated output must declare its own truncation"
        );

        let short = "gate policy file unreadable";
        assert_eq!(
            bounded_masked_log_text(short),
            short,
            "short clean text passes through unchanged"
        );
    }

    #[test]
    fn bounded_masked_log_text_masks_low_entropy_password_past_old_truncation_bound() {
        // Regression: masking used to run AFTER truncating the raw input to a
        // few KB, so a connection string whose password ran past that bound
        // lost its terminating `@` before the url-userinfo detector (a
        // shape match, not an entropy one) ever saw it — a low-entropy
        // password can't trip the entropy heuristic either, so it leaked
        // verbatim into the log. Masking now runs on the full input first,
        // so a password far longer than the old 4096-char bound is still
        // caught.
        let long_low_entropy_password = "a".repeat(5_000);
        let raw = format!(
            "gate backend probe failed: postgres://svc:{long_low_entropy_password}@internal-host refused"
        );
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains(&"a".repeat(50)),
            "long low-entropy password must not survive in the log: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "masked marker must record that the credential was redacted: {rendered:?}"
        );
    }

    /// Regression for the crossing-boundary leak: a password longer than
    /// [`MAX_LOG_TEXT_MASK_INPUT_CHARS`] never gets a chance to show its
    /// terminating `@` to `find_url_userinfo` inside the truncated scan
    /// input, so the shape detector alone can never catch it — and it's
    /// deliberately low-entropy so the entropy heuristic can't catch it
    /// either. Only `redact_crossing_boundary_url_userinfo` can close this.
    #[test]
    fn bounded_masked_log_text_redacts_password_crossing_mask_input_cap() {
        let huge_low_entropy_password = "a".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
        let raw =
            format!("gate backend probe failed: postgres://svc:{huge_low_entropy_password}@internal-host refused");
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains(&"a".repeat(50)),
            "no password fragment may survive when the password crosses the mask-input cap: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "mask marker must record that the credential was redacted: {rendered:?}"
        );
        assert!(
            rendered.ends_with('…'),
            "truncated record must declare its own incompleteness: {rendered:?}"
        );
    }

    /// Regression: the crossing fallback follows the same empty-username
    /// rule as the canonical detector — `redis://:<password>` with the
    /// terminating `@` beyond the mask-input cap must still be redacted.
    #[test]
    fn bounded_masked_log_text_redacts_crossing_empty_username_password() {
        let huge_low_entropy_password = "b".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
        let raw = format!(
            "gate backend probe failed: redis://:{huge_low_entropy_password}@internal-host refused"
        );
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains(&"b".repeat(50)),
            "no empty-username password fragment may survive the cap crossing: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "mask marker must record that the credential was redacted: {rendered:?}"
        );
    }

    /// Regression: the crossing fallback shares the canonical detector's
    /// authority boundary — a colon after `/`, `?`, or `#` is path/query
    /// text, so a capped input whose only colon-at pair sits in the path
    /// must NOT be masked even when the `@` lies beyond the cap.
    #[test]
    fn bounded_masked_log_text_keeps_path_colon_text_crossing_the_cap() {
        let filler = "z".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
        let raw = format!("see https://host/a:x{filler}@next for details");
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains("***MASKED***"),
            "path-colon text must not read as a crossing credential: {rendered:?}"
        );
        assert!(
            rendered.starts_with("see https://host/a:x"),
            "the non-credential prefix must survive verbatim: {rendered:?}"
        );
    }

    /// Regression: a crossing password that itself contains `://` must not
    /// let the fallback anchor at that nested delimiter. Anchoring at the
    /// last `://` would redact only from the nested span onward, leaving
    /// the real `user:<password prefix>` before it in the emitted log. The
    /// fallback must anchor at the earliest unterminated credential
    /// opening, so zero password characters survive.
    #[test]
    fn bounded_masked_log_text_redacts_crossing_password_containing_nested_scheme() {
        let mut password = "a".repeat(1000);
        password.push_str("://h:");
        password.push_str(&"b".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000));
        let raw =
            format!("gate backend probe failed: postgres://svc:{password}@internal-host refused");
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains(&"a".repeat(50)),
            "password prefix before the nested delimiter must not survive: {rendered:?}"
        );
        assert!(
            !rendered.contains(&"b".repeat(50)),
            "password tail after the nested delimiter must not survive: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "mask marker must record that the credential was redacted: {rendered:?}"
        );
    }

    /// Regression: a complete URL earlier in the text must not stop the
    /// fallback from catching a later credential run that crosses the cap.
    /// The earlier URL's span terminates inside the text (whitespace after
    /// it), so it is skipped; the later unterminated `user:<password-run>`
    /// is the one redacted.
    #[test]
    fn bounded_masked_log_text_redacts_crossing_credential_after_complete_url() {
        let huge_low_entropy_password = "c".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
        let raw = format!(
            "probe of https://ok-host/health failed; retry hit postgres://svc:{huge_low_entropy_password}@internal-host refused"
        );
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            rendered.contains("ok-host"),
            "the earlier complete URL must survive untouched: {rendered:?}"
        );
        assert!(
            !rendered.contains(&"c".repeat(50)),
            "no password fragment may survive: {rendered:?}"
        );
        assert!(
            rendered.contains("***MASKED***"),
            "mask marker must record that the credential was redacted: {rendered:?}"
        );
    }

    /// Regression: the crossing-boundary fallback must not fire when the
    /// password's terminating `@` sits safely inside the (untruncated)
    /// bounded input — the existing `find_url_userinfo` arm alone must
    /// still catch and mask it, with exactly one mask marker.
    #[test]
    fn bounded_masked_log_text_masks_password_just_under_cap_with_terminating_at() {
        let password_under_cap = "a".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS - 1000);
        let raw = format!(
            "gate backend probe failed: postgres://svc:{password_under_cap}@internal-host refused"
        );
        assert!(
            raw.chars().count() < MAX_LOG_TEXT_MASK_INPUT_CHARS,
            "test precondition: whole input must stay under the mask-input cap so no truncation occurs"
        );
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains(&"a".repeat(50)),
            "terminated credential must still be masked normally: {rendered:?}"
        );
        assert_eq!(
            rendered.matches("***MASKED***").count(),
            1,
            "exactly one mask marker — the crossing fallback must not fire early: {rendered:?}"
        );
    }

    /// Regression: giant truncated text with no `://user:` shape at all must
    /// pass through unmodified by the crossing-boundary fallback — it must
    /// not manufacture a false redaction out of ordinary non-credential
    /// prose that happens to be long enough to hit the mask-input cap.
    #[test]
    fn bounded_masked_log_text_giant_non_credential_text_unaffected_by_crossing_fallback() {
        let raw = "x".repeat(MAX_LOG_TEXT_MASK_INPUT_CHARS + 1000);
        let rendered = bounded_masked_log_text(&raw);
        assert!(
            !rendered.contains("***MASKED***"),
            "non-credential text must never be redacted: {rendered:?}"
        );
        assert!(
            rendered.ends_with('…'),
            "truncated record must still declare its own incompleteness: {rendered:?}"
        );
        assert!(
            rendered.starts_with("xxxx"),
            "non-credential content must survive verbatim up to the output bound: {rendered:?}"
        );
    }

    /// Regression: an ordinary short connection string (well under both
    /// caps) must keep being masked exactly as before — the crossing
    /// fallback is gated on truncation and must never touch this path.
    #[test]
    fn bounded_masked_log_text_masks_ordinary_short_connection_string() {
        let raw = "gate backend probe failed: postgres://svc:hunter2pw@internal-host refused"; // gitleaks:allow
        let rendered = bounded_masked_log_text(raw);
        assert!(
            !rendered.contains("hunter2pw"),
            "credential must be masked: {rendered:?}"
        );
        assert_eq!(
            rendered.matches("***MASKED***").count(),
            1,
            "exactly one mask marker for the one credential: {rendered:?}"
        );
        assert!(
            !rendered.ends_with('…'),
            "short untruncated text must not declare truncation: {rendered:?}"
        );
    }

    #[test]
    fn bounded_masked_log_text_neutralizes_ascii_control_chars() {
        let raw = "line one\r\ninjected: \u{1b}[31mFAKE ALERT\u{1b}[0m line two";
        let rendered = bounded_masked_log_text(raw);
        assert!(
            !rendered.contains('\r') && !rendered.contains('\n'),
            "CR/LF must be neutralized so a single log line cannot be split/forged: {rendered:?}"
        );
        assert!(
            !rendered.contains('\u{1b}'),
            "ESC control character must be neutralized: {rendered:?}"
        );
        assert!(
            rendered.contains("line one") && rendered.contains("line two"),
            "surrounding prose must survive neutralization: {rendered:?}"
        );
    }

    #[test]
    fn bounded_masked_log_text_neutralizes_each_unsafe_unicode_category() {
        let cases = [
            ("Cc", '\u{1b}', "\\u{001b}"),
            ("Cf", '\u{202e}', "\\u{202e}"),
            ("Zl", '\u{2028}', "\\u{2028}"),
            ("Zp", '\u{2029}', "\\u{2029}"),
        ];

        for (category, unsafe_char, escaped) in cases {
            let raw = format!("before{unsafe_char}after");
            assert_eq!(
                bounded_masked_log_text(&raw),
                format!("before{escaped}after"),
                "Unicode category {category} must be neutralized"
            );
        }
    }

    #[test]
    fn bounded_masked_log_text_keeps_space_separators_tabs_accented_and_cjk_text() {
        let raw = "ordinary whitespace\tcafé résumé 日本語のテキスト\u{3000}数据库连接管理";
        assert_eq!(
            bounded_masked_log_text(raw),
            raw,
            "ordinary whitespace, Zs separators, accented text, and CJK prose must pass through unmodified"
        );
    }

    #[test]
    fn mask_secrets_borrows_clean_text() {
        let clean = "The FlashAttention paper introduces IO-aware tiling.";
        let masked = mask_secrets(clean);
        assert!(
            matches!(masked, std::borrow::Cow::Borrowed(_)),
            "clean text must not allocate"
        );
        assert_eq!(masked, clean);
    }

    #[test]
    fn named_redaction_surfaces_are_permanently_mask_only() {
        let contracts = [
            (RedactionSurface::GitIngest, Some(GIT_INGEST_STORED_TARGET)),
            (
                RedactionSurface::SessionMirror,
                Some(SESSION_MIRROR_STORED_TARGET),
            ),
            (RedactionSurface::McpDiagnostic, None),
            (RedactionSurface::GateProbe, None),
        ];

        for (surface, expected_target) in contracts {
            let contract = redaction_surface_contract(surface);
            assert_eq!(contract.mode, RedactionSurfaceMode::PermanentMaskOnly);
            assert_eq!(contract.final_stored_target, expected_target);
            assert_eq!(contract.stamp_property, None);
            assert_eq!(contract.atomic_success_event, None);
        }
    }

    #[test]
    fn named_redaction_surfaces_mask_without_exemption_admission() {
        let content = format!("credential: {}", openai_project_key_fixture());

        for surface in [
            RedactionSurface::GitIngest,
            RedactionSurface::SessionMirror,
            RedactionSurface::McpDiagnostic,
            RedactionSurface::GateProbe,
        ] {
            let masked = mask_for_redaction_surface(surface, &content);
            assert!(masked.contains(REDACTION_MARKER));
            assert!(check(masked.as_ref()).is_ok());
        }
    }

    #[test]
    fn mask_bounded_matches_unbounded_masking_when_input_fits_the_window() {
        let content = format!("credential: {}", openai_project_key_fixture());
        let expected = mask_for_redaction_surface(RedactionSurface::McpDiagnostic, &content);
        let result = mask_bounded(RedactionSurface::McpDiagnostic, &content, 4_096, 1_024);
        assert_eq!(result.text, expected.as_ref());
        assert!(!result.truncated);
        assert!(result.redacted);
    }

    #[test]
    fn mask_bounded_masks_a_credential_whose_terminator_sits_inside_the_window() {
        // The window is far larger than the message, and the credential's
        // terminating `@` sits well inside it — the ordinary case where the
        // masker sees the whole token and can recognize its shape.
        let password = format!("PlainPassMarker{}", "q".repeat(24));
        let url = format!("postgres://svc:{password}@internal-host.example.test/db");
        let message = format!("backend probe failed: {url}");
        assert!(message.chars().count() < 200, "fixture must fit the window");

        let result = mask_bounded(RedactionSurface::McpDiagnostic, &message, 200, 100);
        assert!(
            !result.text.contains("PlainPassMarker"),
            "credential must be masked: {}",
            result.text
        );
        assert!(result.text.contains("***MASKED***"));
        assert!(result.redacted);
    }

    #[test]
    fn mask_bounded_drops_a_token_straddling_the_window_boundary_without_partial_leak() {
        // Constructed so the credential token starts before the window ends
        // but its terminating `@` lands well past it — a masker restricted
        // to the window can never observe that `@`, so a truncate-then-mask
        // policy (the pre-fix behavior at this call site) would recognize no
        // span and let the visible prefix, including the marker below,
        // survive untouched in the output. Bounding the input before
        // masking must not reopen that hole: since the token has no internal
        // whitespace, the fix drops it whole rather than emitting any
        // fragment of it.
        let window_chars = 200;
        let marker = "StraddleMarkerXYZ789";
        let padding = "q".repeat(window_chars + 100);
        let password = format!("{marker}{padding}");
        let url = format!("postgres://svc:{password}@internal-host.example.test/db");
        let message = format!("benign leading prose here {url}");

        let at_offset = message.find('@').expect("fixture must contain '@'");
        assert!(
            at_offset > window_chars,
            "credential must straddle the window"
        );

        let result = mask_bounded(RedactionSurface::McpDiagnostic, &message, window_chars, 100);
        assert!(
            !result.text.contains(marker),
            "no fragment of the credential may survive: {}",
            result.text
        );
        assert!(
            !result.text.contains("postgres://"),
            "the straddling token must be dropped whole, not partially echoed: {}",
            result.text
        );
        assert!(result.truncated);
    }

    #[test]
    fn mask_bounded_replaces_a_single_oversized_token_with_the_truncation_marker_alone() {
        // One token (no whitespace anywhere) longer than the window: there is
        // no earlier whitespace to fall back to, so nothing from the window
        // can be shown safely.
        let window_chars = 50;
        let text = "q".repeat(window_chars * 4);

        let result = mask_bounded(RedactionSurface::McpDiagnostic, &text, window_chars, 20);
        assert_eq!(result.text, "…");
        assert!(result.truncated);
        assert!(result.redacted);
    }

    #[test]
    fn mask_bounded_bounds_output_to_the_window_regardless_of_input_size() {
        // Several megabytes of benign, whitespace-separated text. A
        // truncate-then-mask or mask-then-truncate policy alike would still
        // need to allocate and scan the full input before this function ever
        // gets to cap the *output*; the point of `mask_bounded` is that the
        // *masker* itself only ever sees `window_chars`. That is asserted
        // here as a length invariant (never by wall-clock): the returned
        // text can never exceed the window, no matter how large the input.
        let window_chars = 4_096;
        let huge = "benign word ".repeat(500_000);
        assert!(huge.len() > 5_000_000, "fixture must be several megabytes");

        let result = mask_bounded(RedactionSurface::McpDiagnostic, &huge, window_chars, 500);
        assert!(result.truncated);
        assert!(result.text.chars().count() <= 501);
    }

    /// A 40-hex-char credential (the SHA-1/git-SHA-doubled shape) built at
    /// test time by cycling a short literal, never committed whole.
    fn forty_char_hex_fixture() -> String {
        "a1b2c3d4e5f6".chars().cycle().take(40).collect()
    }

    #[test]
    fn mask_bounded_masks_a_bridged_credential_whose_fragments_straddle_the_window_boundary() {
        // A 40-char hex credential split into two whitespace-separated
        // fragments, each individually too short (20 chars) to be
        // recognized as hex-credential-shaped or high-entropy on its own —
        // recoverable only by bridging the two fragments together. Expected
        // arm: before the fix, the window cut lands inside the second
        // fragment, the existing partial-token drop removes only that
        // fragment's remnant, and the first fragment (alone, unrecognizable)
        // survives visible in the bounded output.
        let hex = forty_char_hex_fixture();
        let (frag1, frag2) = hex.split_at(20);
        let message = format!("credential: {frag1} {frag2}");

        // Control: the unbounded masker sees both fragments and masks the
        // reconstructed credential.
        let full = mask_for_redaction_surface(RedactionSurface::McpDiagnostic, &message);
        assert!(
            !full.contains(frag1) && !full.contains(frag2),
            "control: unbounded masking must reconstruct and mask the split credential: {full}"
        );

        // Land the window a few characters into frag2, so the existing
        // partial-token drop removes only frag2's remnant.
        let window_chars = "credential: ".len() + frag1.len() + 1 + 5;
        assert!(
            window_chars < message.len(),
            "fixture must exceed the window"
        );

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(result.truncated);
        assert!(
            !result.text.contains(frag1),
            "no fragment of a bridged credential may survive a window cut mid-chain: {:?}",
            result.text
        );
        assert!(result.redacted);
    }

    #[test]
    fn mask_bounded_masks_a_bridged_credential_entirely_inside_the_window() {
        // Control: both fragments AND the rest of the message fit inside the
        // window — ordinary in-window bridge reconstruction, unaffected by
        // the boundary-drop logic.
        let hex = forty_char_hex_fixture();
        let (frag1, frag2) = hex.split_at(20);
        let message = format!("credential: {frag1} {frag2} trailing prose after the secret");
        let window_chars = message.chars().count() + 10;

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(!result.truncated);
        assert!(!result.text.contains(frag1));
        assert!(!result.text.contains(frag2));
    }

    #[test]
    fn mask_bounded_never_reveals_a_bridged_credential_entirely_outside_the_window() {
        // Control: the window cut lands well before the credential even
        // starts, so neither fragment is ever read into the window.
        let hex = forty_char_hex_fixture();
        let (frag1, frag2) = hex.split_at(20);
        let prefix = "benign leading prose that pads well past the cut point here ";
        let message = format!("{prefix}credential: {frag1} {frag2}");
        let window_chars = prefix.chars().count() - 10;

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(!result.text.contains(frag1));
        assert!(!result.text.contains(frag2));
    }

    #[test]
    fn mask_bounded_masks_a_bridged_credential_whose_trigger_follows_the_window() {
        // Three-way split (14/13/13 chars) of a 40-char hex credential, each
        // fragment individually too short to be recognized alone. The only
        // trigger word sits AFTER the last fragment ("... is the api key
        // for ..."), never inside the truncated window. Expected arm
        // (pre-fix): `trailing_bridge_fragment_cut` gated its backward walk
        // on a trigger word in the window, and the window here carries no
        // trigger at all — the walk never ran, so frag1 and frag2 (both
        // read whole into the window) survived the partial-token drop and
        // leaked.
        let hex = forty_char_hex_fixture();
        let (frag1, rest) = hex.split_at(14);
        let (frag2, frag3) = rest.split_at(13);
        let message = format!("values: {frag1} {frag2} {frag3} is the api key for the service");

        // Control: the unbounded masker sees the trigger after the
        // fragments and still reconstructs and masks the whole credential.
        let full = mask_for_redaction_surface(RedactionSurface::McpDiagnostic, &message);
        assert!(
            !full.contains(frag1) && !full.contains(frag2) && !full.contains(frag3),
            "control: unbounded masking must reconstruct and mask the split \
             credential even though its trigger word comes after the \
             fragments: {full}"
        );

        // Land the window a few characters into frag3, so the existing
        // partial-token drop removes only frag3's remnant and leaves frag1
        // and frag2 whole in the window; the trigger word stays entirely
        // outside the window.
        let window_chars = "values: ".len() + frag1.len() + 1 + frag2.len() + 1 + 5;
        assert!(
            window_chars < message.len(),
            "fixture must exceed the window"
        );
        assert!(
            find_trigger(&message[..window_chars], false).is_none(),
            "fixture must carry no trigger word inside the window"
        );

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(result.truncated);
        assert!(
            !result.text.contains(frag1) && !result.text.contains(frag2),
            "no fragment of a bridged credential may survive a window cut \
             mid-chain, even when the credential's only trigger word lies \
             past the window boundary: {:?}",
            result.text
        );
    }

    #[test]
    fn mask_bounded_keeps_a_non_fragment_tail_of_an_untriggered_truncated_window() {
        // No trigger word anywhere in the message, and the tokens at the
        // tail of the truncated window are ordinary short words (each under
        // `MIN_BRIDGE_FRAGMENT_LEN`) rather than fragment-shaped. The
        // unconditional backward walk must still leave them alone: nothing
        // at the tail looks like a bridged credential fragment.
        let prefix = "benign status update about the lazy owls and cats over ";
        let message = format!("{prefix}here while more prose keeps going past the window");
        assert!(
            find_trigger(&message, false).is_none(),
            "fixture must carry no trigger word"
        );
        let window_chars = prefix.chars().count() + 2;

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(result.truncated);
        assert_eq!(result.text, format!("{prefix}{TRUNCATION_MARKER}"));
    }

    #[test]
    fn mask_bounded_drops_a_fragment_shaped_tail_of_an_untriggered_truncated_window() {
        // No trigger word anywhere in the message. A single fragment-shaped
        // identifier (alphanumeric, >= MIN_BRIDGE_FRAGMENT_LEN) sits whole
        // in the window, followed by a short word that gets cut mid-token by
        // the boundary. Documents the trade the unconditional walk makes:
        // the walk cannot tell this lone identifier apart from a genuine
        // bridged fragment, so it drops it too even though nothing is
        // actually chained to it and no trigger word is anywhere nearby.
        let prefix = "an ordinary status line about the current build before ";
        let identifier = "deadbeefcafefeed01234567";
        let message = format!("{prefix}{identifier} zzzzzzzzzz");
        assert!(
            find_trigger(&message, false).is_none(),
            "fixture must carry no trigger word"
        );
        assert!(identifier.len() >= MIN_BRIDGE_FRAGMENT_LEN);

        let window_chars = prefix.chars().count() + identifier.chars().count() + 1 + 3;
        assert!(
            window_chars < message.len(),
            "fixture must exceed the window"
        );

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(result.truncated);
        assert!(
            !result.text.contains(identifier),
            "a lone fragment-shaped tail token is dropped even without a \
             chained neighbor or a trigger word: {:?}",
            result.text
        );
    }

    #[test]
    fn mask_bounded_keeps_the_whole_token_prefix_of_an_untriggered_sentence_cut_mid_word() {
        // No trigger word anywhere in the message: the boundary-drop must
        // never fire, so the existing partial-token-drop behavior is
        // unchanged and nothing extra is dropped.
        let prefix = "the quick brown fox jumps over the lazy ";
        let message = format!("{prefix}dogs while writing documentation");
        assert!(
            find_trigger(&message, false).is_none(),
            "fixture must carry no trigger word"
        );
        let window_chars = prefix.chars().count() + 2;

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            &message,
            window_chars,
            window_chars,
        );
        assert!(result.truncated);
        assert_eq!(result.text, format!("{prefix}{TRUNCATION_MARKER}"));
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic(expected = "the input window must stay at least as large as the output cap")]
    fn mask_bounded_debug_asserts_when_window_is_smaller_than_output_cap() {
        let _ = mask_bounded(
            RedactionSurface::McpDiagnostic,
            "some diagnostic text",
            10,
            50,
        );
    }

    #[test]
    #[cfg(not(debug_assertions))]
    fn mask_bounded_clamps_output_cap_to_window_chars_outside_debug_assertions() {
        // Inverted pair (window_chars < output_cap_chars): outside debug
        // assertions this must not panic, and the returned text must
        // respect window_chars as the effective cap, never the larger
        // output_cap_chars a misconfigured call site passed in. Uses a
        // degenerate `scheme://user:pass@host` short enough (9 chars) that
        // its `***MASKED***` replacement (12 chars) GROWS past window_chars
        // — the one case where an uncapped `output_cap_chars` would let the
        // returned text exceed the window it was supposed to be bounded by.
        let window_chars = 9;
        let output_cap_chars = 500;
        let text = "a://b:c@d"; // scheme=a, user=b, pass=c, host=d — 9 chars, fits the window whole
        assert_eq!(
            text.len(),
            window_chars,
            "fixture must exactly fill the window"
        );

        let result = mask_bounded(
            RedactionSurface::McpDiagnostic,
            text,
            window_chars,
            output_cap_chars,
        );
        assert!(
            result.text.chars().count() <= window_chars + 1,
            "output must never exceed the window (plus one truncation-marker char) \
             even when output_cap_chars is misconfigured larger than window_chars: {:?}",
            result.text
        );
    }

    #[test]
    fn mask_secrets_redacts_shapes_the_old_mirror_regex_missed() {
        // These are exactly the detectors the session mirror's previous local
        // regex did NOT cover, which is why it now shares this masker.
        let cases = [
            format!("key: {}", openai_project_key_fixture()),
            "cred ASIAFAKEKEY00000000000".to_owned(), // gitleaks:allow
            "stripe sk_live_FAKESTRIPE0000000000000".to_owned(), // gitleaks:allow
            "db postgresql://dbuser:S3cr3tP4ss@db.example.com/db".to_owned(), // gitleaks:allow
        ];
        for c in &cases {
            let masked = mask_secrets(c);
            assert!(
                masked.contains(REDACTION_MARKER),
                "must redact: {c:?} -> {masked:?}"
            );
        }
    }

    #[test]
    fn mask_secrets_redacts_every_span_and_keeps_prose() {
        let line = format!(
            "first {} then ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA end",
            anthropic_api_key_fixture()
        );
        let masked = mask_secrets(&line);
        assert!(
            !masked.contains("sk-ant-api03") && !masked.contains("ghp_AAAA"),
            "no secret may survive: {masked}"
        );
        assert_eq!(
            masked.matches(REDACTION_MARKER).count(),
            2,
            "both secrets must be redacted: {masked}"
        );
        assert!(masked.starts_with("first "), "prose preserved: {masked}");
        assert!(masked.ends_with(" end"), "prose preserved: {masked}");
    }

    #[test]
    fn mask_secrets_public_api_redacts_unscanned_dense_tail() {
        let token = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
        let segment = format!("{token} keep ");
        // Keep this fixture independent of implementation-only constants: the
        // pre-bound implementation must compile with the test present.
        let line = segment.repeat(512);
        assert!(
            line.len() >= 20_000,
            "fixture must exceed the cumulative scan-work threshold"
        );

        let masked = mask_secrets(&line);
        assert!(
            !masked.contains(token),
            "no credential may survive fail-closed tail redaction"
        );
        assert!(
            masked.matches("***MASKED***").count() < line.matches(token).count(),
            "the public masker must redact the unscanned tail wholesale"
        );
        assert!(
            masked.ends_with("***MASKED***"),
            "the fail-closed tail redaction must reach the end of the public result"
        );
    }

    // White-box complement only: the public test above is the independent
    // guard for the fail-closed work bound.
    #[test]
    fn mask_secrets_tokenizes_concentrated_tail_once() {
        let token = "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
        let prefix = "clean ".repeat(1_000_000 / "clean ".len());
        let tail: String = (0..200).map(|_| format!("{token} ")).collect();
        let line = format!("{prefix}{tail}");
        assert_eq!(line.matches(token).count(), 200);

        ENTROPY_TOKENIZATION_COUNT.with(|count| count.set(0));
        let masked = mask_secrets(&line);
        let tokenization_count = ENTROPY_TOKENIZATION_COUNT.with(|count| count.get());

        assert!(
            !masked.contains(token),
            "the public masker must redact every concentrated-tail credential"
        );
        assert_eq!(
            tokenization_count, 1,
            "the full input token vector must be built once, not once per tail credential"
        );
    }

    #[test]
    fn mask_secrets_output_passes_check() {
        // The masked output must itself be clean — no credential left for the
        // write-time gate to catch.
        let line = "token=ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA and AKIAFAKEKEY1234567890";
        let masked = mask_secrets(line).into_owned();
        assert!(
            check(&masked).is_ok(),
            "masked output must pass the gate: {masked}"
        );
    }

    #[test]
    fn mask_secrets_redacts_entropy_secret_left_of_known_secret() {
        // Cross-layer leftmost regression: a Layer-2 entropy secret sits to the
        // LEFT of a Layer-1 known-prefix secret. A scan that short-circuits on
        // the first known match (or returns first-by-detector-priority) would
        // redact `ghp_…` and copy the entropy token before it verbatim — leaking
        // it. `scan_match` must fold both layers through leftmost selection.
        let line =
            "secret=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM and ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"; // gitleaks:allow
        let masked = mask_secrets(line).into_owned();
        assert!(
            !masked.contains("Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM") && !masked.contains("ghp_AAAA"),
            "neither the entropy secret nor the known secret may survive: {masked}"
        );
        assert_eq!(
            masked.matches(REDACTION_MARKER).count(),
            2,
            "both secrets must be redacted exactly once: {masked}"
        );
        assert!(
            check(&masked).is_ok(),
            "masked output must pass the gate: {masked}"
        );
    }

    #[test]
    fn github_app_token_families_are_masked() {
        // ghu_ (user-to-server), ghs_ (server-to-server), and ghr_ (refresh)
        // GitHub App tokens are real credential families. They are
        // context-free: no trigger word needed.
        let cases = [
            "ghu_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // gitleaks:allow
            "ghs_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",  // gitleaks:allow
            "ghr_CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC",  // gitleaks:allow
        ];
        for token in &cases {
            assert!(
                check(token).is_err(),
                "gate must hard-block GitHub App token {token}"
            );
            let line = format!("auth: {token} trailing");
            let masked = mask_secrets(&line).into_owned();
            assert!(
                !masked.contains(token),
                "GitHub App token must not survive masking: {masked}"
            );
            assert!(
                check(&masked).is_ok(),
                "masked output must pass the gate: {masked}"
            );
        }
    }

    #[test]
    fn mask_secrets_redacts_entropy_token_whose_trigger_is_left_of_earlier_secret() {
        // The entropy detector only fires near a
        // trigger word. When the trigger (`api_key`) sits to the LEFT of an
        // earlier known-prefix secret (`ghp_…`), a masker that rescans only the
        // suffix after each redaction loses that context and leaks the later
        // high-entropy token. Spans must be discovered against the ORIGINAL text.
        let line =
            "api_key ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"; // gitleaks:allow
        let masked = mask_secrets(line).into_owned();
        assert!(
            !masked.contains("ghp_AAAA"),
            "the known secret must be redacted: {masked}"
        );
        assert!(
            !masked.contains("Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM1"),
            "the later entropy token must be redacted even though its trigger \
             word sits left of the earlier redaction: {masked}"
        );
        assert_eq!(
            masked.matches(REDACTION_MARKER).count(),
            2,
            "both secrets must be redacted exactly once: {masked}"
        );
        assert!(
            check(&masked).is_ok(),
            "masked output must pass the gate: {masked}"
        );
    }

    // ── Structured identifiers: file paths / branch names ───────────────────

    #[test]
    fn allows_high_entropy_file_path_near_secret_word() {
        let content =
            "workspace path fable-ops/ADR-DRAFT-adr079-slices234.md for the secret gate bug";
        assert!(
            check(content).is_ok(),
            "structured file path in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_high_entropy_workspace_path_before_later_key_word() {
        let content =
            "see internal/workspaces/20260701/adr079-slices234/PACKET.md for the key behavior";
        assert!(
            check(content).is_ok(),
            "a path before a later topical key word must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_high_entropy_short_run_path_near_auth_word() {
        let content =
            "auth work saved at internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
        assert!(
            check(content).is_ok(),
            "path with a short run in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_branch_and_review_filename_near_key_word() {
        let content =
            "branch feat-session-mirror pushed, see release_notes_v2.md for the key findings";
        assert!(
            check(content).is_ok(),
            "branch name and review filename near 'key' must not be blocked; fired: {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_adr_doc_path_near_password_word() {
        let content = "password reset doc: docs/adr/ADR-055-epistemic-edge-relations.md";
        assert!(
            check(content).is_ok(),
            "ADR doc path near 'password' must not be blocked; fired: {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_source_file_path_near_credential_word() {
        let content = "credential handling code crates/khive-pack-session/src/mirror/ingest.rs";
        assert!(
            check(content).is_ok(),
            "source file path near 'credential' must not be blocked; fired: {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_long_snake_case_identifier_near_key_word() {
        let content = "api key handling lives in check_entropy_heuristic_impl";
        assert!(
            check(content).is_ok(),
            "snake_case identifier near 'key' must not be blocked; fired: {:?}",
            scan(content)
        );
    }

    // ── Structured-identifier exemption: catch-suite regression ─────────────

    #[test]
    fn hyphenated_random_secret_is_not_a_structured_identifier() {
        // Same token as `blocks_bare_base64url_43chars_near_key`: hyphenated
        // but not word-shaped. The second run exceeds the 24-char run cap,
        // and the first run's case-transition density (~0.42) exceeds the
        // 0.3 threshold on its own, so this must not be exempted and the
        // existing catch-suite test must keep blocking it.
        assert!(!is_structured_identifier(
            "wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123"
        ));
        let line = "api key wJalrXUtnFEMI-K7MDENGbPxRfiCYEXAMPLEKEYX123";
        assert!(
            scan(line).is_some(),
            "hyphenated random secret must still be blocked; got: {:?}",
            scan(line)
        );
    }

    // ── Structured-identifier exemption: direct unit tests ───────────────────

    #[test]
    fn structured_identifier_true_for_repro_paths() {
        let paths = [
            "fable-ops/ADR-DRAFT-adr079-slices234.md",
            "internal/workspaces/20260701/adr079-slices234/PACKET.md",
            "internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md",
            "release_notes_v2.md",
            "docs/adr/ADR-055-epistemic-edge-relations.md",
            "crates/khive-pack-session/src/mirror/ingest.rs",
            "check_entropy_heuristic_impl",
        ];
        for p in paths {
            assert!(
                is_structured_identifier(p),
                "expected structured identifier: {p}"
            );
        }
    }

    #[test]
    fn structured_identifier_false_without_separator() {
        // No `/`, `-`, `_`, or `.` present — fails rule 1 outright.
        assert!(!is_structured_identifier(
            "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM"
        ));
    }

    #[test]
    fn structured_identifier_false_for_leetspeak_digit_interleaving() {
        // Digits interleaved with letters within a run (not a trailing digit
        // suffix) fail the `[A-Za-z]+[0-9]*` / `[0-9]+` shape check.
        assert!(!is_structured_identifier("S3cr3t-P4ssw0rd-t0ken-here!"));
    }

    #[test]
    fn structured_identifier_false_for_run_over_length_cap() {
        // A 26-char single alphabetic run between separators fails the
        // 24-char per-run length cap even though it is otherwise trivially
        // word-shaped (uniform lowercase, zero case transitions).
        let long_run = "a".repeat(26);
        let token = format!("prefix-{long_run}-suffix");
        assert!(!is_structured_identifier(&token));
    }

    // ── Credential-labeled structured identifiers remain blocked ────────────
    // Shannon entropy over an attacker-chosen run boundary cannot distinguish an
    // English word from adversarially-chosen letters at the same length ceiling
    // (log2(run_len)), so no run-shape exemption is sound near a trigger. File paths
    // are exempt only after their runs pass the entropy/hex checks AND the path is
    // not immediately labeled as a credential value. The tests below guard that
    // credential-label boundary.

    #[test]
    fn blocks_separator_secret_access_key_bypass() {
        // Adversarial bypass shape: an AWS-secret-key-like value split into
        // separator-delimited word-shaped runs to dodge the entropy check.
        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk";
        assert!(
            check(content).is_err(),
            "AWS Secret Access Key shaped bypass must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_adversarial_lowercase_only_separator_token_near_access_key() {
        let content = "access_key qrstuvwxyz/abcdefghij/klmnopqrst/uvwxyzab";
        assert!(
            check(content).is_err(),
            "lowercase-only separator-delimited high-entropy token near \
             'access_key' must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_adversarial_digit_and_word_mixed_token_near_api_key() {
        // A mix of pure-digit runs and letters-then-digits runs (both
        // individually word-shaped) whose combined alphabet diversity crosses
        // the entropy threshold.
        let content = "api_key attaycofrsm827/festwqjhc493/8261947350/qwikjzx982";
        assert!(
            check(content).is_err(),
            "digit-and-word-mixed high-entropy token near 'api_key' must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_adversarial_token_assignment_separator_delimited_secret() {
        let content = "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk";
        assert!(
            check(content).is_err(),
            "token= with lowercase-only separator-delimited high-entropy value \
             must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_extension_suffix_bypass_secret_access_key() {
        // A file-extension check alone would exempt this: appending `.md`
        // to a random credential must not bypass detection.
        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk.md";
        assert!(
            check(content).is_err(),
            "extension-suffixed AWS Secret Access Key shaped bypass must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_extension_suffix_bypass_token_assignment() {
        let content = "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk.rs";
        assert!(
            check(content).is_err(),
            "extension-suffixed token= bypass must be blocked: {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_unsuffixed_separator_split_credential_bypasses() {
        let cases = [
            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk",
            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz-mnbvcxzlk",
        ];
        for content in cases {
            assert!(
                check(content).is_err(),
                "bypass string must still be blocked: {content:?}, got: {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_digit_run_suffix_bypass_attempt() {
        let cases = [
            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk2024",
            "secret_access_key abcdefghij2024/klmnopqrst/uvwxyzabcd/efghijk.md",
        ];
        for content in cases {
            assert!(
                check(content).is_err(),
                "digit-run-suffixed bypass attempt must be blocked: {content:?}, got: {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_low_entropy_padding_run_bypass_attempts() {
        // A low-entropy padding run (`aaaa`) inserted before short/digit-shaped
        // runs would drag any AVERAGE per-run entropy signal below its
        // threshold. With the exemption dropped entirely, these must be
        // blocked purely on full-token entropy, same as any other
        // near-trigger high-entropy token.
        let cases = [
            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk/aaaa/R1.md",
            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz/mnbvcxzlk/aaaa/R1.rs",
            "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk/aaaa/bbbb/R1.md",
            "token=zxkqwmvbpl/trfhysjgnc/dweiaoutkz/mnbvcxzlk/aaaa/bbbb/R1.rs",
        ];
        for content in cases {
            assert!(
                check(content).is_err(),
                "padding-run bypass attempt must be blocked: {content:?}, got: {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_run_splitting_bypass_attempts() {
        // Splitting a credential into short (4-6 char) runs drives EVERY
        // run's own letters-only entropy toward log2(run_len), which ordinary
        // short English path words already sit at or near: this is exactly
        // why any per-run entropy ceiling is unsound as an exemption signal.
        // With the exemption dropped, these are blocked on full-token entropy
        // regardless of run shape.
        let cases = [
            "secret_access_key abcd/efgh/ijkl/mnop/qrst/uvwx/yzab/cdef.md",
            "secret_access_key abcde/fghij/klmno/pqrst/uvwxy/zabcd.md",
            "secret_access_key abcdef/ghijkl/mnopqr/stuvwx/yzabcd.md",
        ];
        for content in cases {
            assert!(
                check(content).is_err(),
                "run-splitting bypass attempt must be blocked: {content:?}, got: {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_separator_split_generic_hex_credential_ascii() {
        // Two 20-char hex runs joined by `/` — individually
        // below MIN_ENTROPY_LEN (24) and neither is a HEX_CREDENTIAL_LENGTHS
        // length on its own; the whole token is not pure hex (the `/` breaks
        // it) and its entropy is capped below ENTROPY_THRESHOLD by the
        // 17-symbol hex-plus-separator alphabet, so none of the prior checks
        // caught it. Concatenating the two runs (dropping the separator)
        // normalizes to one 40-char hex sequence — a HEX_CREDENTIAL_LENGTHS
        // value.
        let content = "api key 0123456789abcdef0123/456789abcdef01234567";
        assert!(
            check(content).is_err(),
            "separator-split hex credential must be blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_separator_split_generic_hex_credential_unicode_separator() {
        // Same shape as above, but the separator is a non-ASCII character
        // (U+200B zero-width space) instead of `/`: the tokenizer treats
        // every non-ASCII character as a delimiter (see the tokenizer
        // comment in `check_entropy_heuristic`), so this splits the payload
        // into TWO tokens rather than leaving it inside one — the
        // intra-token concatenation above never sees both halves together.
        // The adjacent-token bridge must catch it the same way.
        let content = "api key 0123456789abcdef0123\u{200B}456789abcdef01234567";
        assert!(
            check(content).is_err(),
            "Unicode-separator split hex credential must be blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_unicode_split_hex_credential_with_path_shaped_anchor() {
        let content =
            "api key handling uses source/x/0123456789abcdef0123\u{200B}456789abcdef01234567";
        let tokens: Vec<(usize, &str)> = content
            .split(|c: char| c.is_ascii_whitespace() || !c.is_ascii())
            .filter(|token| !token.is_empty())
            .map(|token| (token.as_ptr() as usize - content.as_ptr() as usize, token))
            .collect();
        let anchor = tokens
            .iter()
            .position(|(_, token)| token.starts_with("source/"))
            .expect("path anchor must be tokenized");
        assert!(is_plausible_file_path(tokens[anchor].1));
        let fragments = bridge_fragment_chain(&tokens, content, anchor);
        assert_eq!(fragments.len(), 2);
        assert!(normalized_hex_credential_span(&fragments.join(" ")).is_some());
        assert!(
            check(content).is_err(),
            "path-shaped anchor must not bypass fragment reconstruction: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_separator_split_hex_credential_repeated_unicode_gap() {
        // Three U+200B zero-width spaces in a row
        // (9 bytes) would exceed a fixed byte-length gap bound (e.g. 8 bytes),
        // leaving the two 20-char hex halves unbridged. The fragment-chain
        // bridge is bounded by fragment COUNT (MAX_BRIDGE_FRAGMENTS), not
        // gap byte length, so repeating the delimiter buys an attacker
        // nothing: the gap between the two fragments still contains zero
        // ASCII alphanumeric characters, so it is still one bridgeable gap
        // regardless of how many times the delimiter repeats inside it.
        let content = "api key 0123456789abcdef0123\u{200B}\u{200B}\u{200B}456789abcdef01234567";
        assert!(
            check(content).is_err(),
            "repeated-Unicode-gap split hex credential must be blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_separator_split_three_way_hex_credential_mixed_case() {
        // A 40-char mixed-case hex credential split
        // into THREE tokens by two single-U+200B gaps. Bridging only one
        // adjacent pair (`idx` with `idx + 1`, or `idx` with
        // `idx - 1`) would never reach the full
        // 40 chars. `bridge_fragment_chain` walks a bounded chain in both
        // directions, so starting from the first fragment reconstructs all
        // three. `is_ascii_hexdigit` accepts both cases, so the mixed-case
        // split (`AAAA...` alongside lowercase `cccc...`) must still
        // normalize to one 40-char hex sequence.
        let content = "api key AAAA1111bbbb22\u{200B}22cccc3333ddd\u{200B}d4444eeee5555";
        assert!(
            check(content).is_err(),
            "three-way mixed-case Unicode-split hex credential must be blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_separator_split_base64_like_unicode_credential() {
        // A base64-like credential (mixed-case
        // alphanumeric, not hex) split by one U+200B into two 20-char
        // halves. A hex-only bridge candidacy gate would only admit pure-hex
        // short tokens, so neither half here (mixed-case, non-hex letters
        // like `X`, `k`, `Z`) ever reached the near-trigger bridge checks at
        // all. `is_bridge_candidate` now admits any short alphanumeric
        // token, and the reconstructed chain is checked against the SAME
        // whole-token entropy decision a genuine single-token high-entropy
        // candidate must clear — closing the hex-only gap without widening
        // detection to non-alphanumeric noise.
        let content = "api key Xk9mZ2vQpLrT8nJwYuAe\u{200B}HfBsDcGiONvMabcdefgh";
        assert!(
            check(content).is_err(),
            "base64-like Unicode-split credential must be blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_punctuation_glue_between_two_unicode_gaps() {
        // Two 20-char hex fragments separated by a punctuation-only token (`---`)
        // sandwiched between two U+200B gaps: `is_delimiter_only_token` must let the
        // walk absorb `---` as glue (without counting it against MAX_BRIDGE_FRAGMENTS)
        // rather than stopping at it as a non-fragment token.
        let content = "api key 0123456789abcdef0123\u{200B}---\u{200B}456789abcdef01234567";
        assert!(
            check(content).is_err(),
            "punctuation-glue split hex credential between two Unicode gaps must be \
             blocked: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_seven_way_hex_split_beyond_fragment_cap_documented_limitation() {
        // A 64-hex credential split into SEVEN
        // Unicode-separated fragments (each meeting MIN_BRIDGE_FRAGMENT_LEN)
        // exceeds MAX_BRIDGE_FRAGMENTS (6), so no chain the walk can build
        // ever reconstructs the full 64 chars. This is an ACCEPTED RESIDUAL
        // of the local-neighborhood bound, not a defect to fix here: per
        // ADR-096 / ADR-115 the secret gate is accidental-persistence
        // hygiene on a single-principal same-uid host, not defense against a
        // same-uid adversary hand-splitting a credential to evade it — that
        // adversary could write the DB directly instead. This test pins the
        // boundary so a future reader does not mistake it for an
        // unaddressed bypass.
        let content = "api key 012345678\u{200B}9abcdef01\u{200B}23456789a\u{200B}bcdef0123\u{200B}456789abc\u{200B}def012345\u{200B}6789abcdef";
        assert!(
            check(content).is_ok(),
            "seven-way hex split beyond MAX_BRIDGE_FRAGMENTS is a documented residual \
             limitation and must stay allowed: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_six_way_sub_floor_hex_split_documented_limitation() {
        // A 40-hex credential split into six
        // Unicode-separated fragments each individually below
        // MIN_BRIDGE_FRAGMENT_LEN (8) — 7/7/7/7/6/6 characters. Every
        // fragment fails `is_bridge_candidate`, so none ever reaches
        // `bridge_fragment_chain` in the first place. Same accepted-residual
        // rationale as the seven-way split above: a same-uid adversary
        // splitting fragments this small to evade the gate can equally
        // write the DB directly. This test pins the boundary.
        let content = "api key 0123456\u{200B}789abcd\u{200B}ef01234\u{200B}56789ab\u{200B}cdef01\u{200B}234567";
        assert!(
            check(content).is_ok(),
            "six-way sub-MIN_BRIDGE_FRAGMENT_LEN hex split is a documented residual \
             limitation and must stay allowed: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_unrelated_short_fragments_cited_near_a_trigger_word() {
        // False-positive guard: ordinary prose
        // citing two SEPARATE short hex/base64-ish identifiers (e.g. two
        // unrelated git SHA prefixes) near a trigger word must NOT combine
        // into a block just because a delimiter-only gap between them makes
        // them bridge-eligible. Each fragment is well under
        // MIN_BRIDGE_FRAGMENT_LEN's credential-length neighborhood, and the
        // reconstructed concatenation (16 chars) is neither a
        // HEX_CREDENTIAL_LENGTHS value nor at MIN_ENTROPY_LEN (24), so it
        // must stay allowed exactly like a real single fragment that short
        // would.
        let content = "api key: see commits abc12345, def67890 for the fix";
        assert!(
            check(content).is_ok(),
            "unrelated short fragments cited near a trigger word must stay allowed: \
             fired {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_unrelated_short_base64_like_fragments_cited_near_a_trigger_word() {
        // Same guard as above, for the newly-widened non-hex/base64-like
        // bridge path specifically: two short mixed-case alphanumeric build
        // identifiers separated by a plain space near a trigger word.
        // Reconstructed length (12 chars) is far under MIN_ENTROPY_LEN (24),
        // so the generic entropy reconstruction must not fire.
        let content = "api key: build ids Ab3Kf9 and Xy7Lm2 do not match";
        assert!(
            check(content).is_ok(),
            "unrelated short base64-like fragments cited near a trigger word must \
             stay allowed: fired {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_scattered_short_hex_runs_that_do_not_sum_to_a_credential_length() {
        // False-positive guard: short hex-looking runs
        // that happen to sit near a trigger word must NOT be flagged just
        // because they exist — only when their normalized concatenation
        // actually lands on a HEX_CREDENTIAL_LENGTHS value. Three
        // independent 8-char runs (running total 8, 16, 24) never hit
        // 32/40/64/128, and the whole-token entropy check that follows stays
        // below ENTROPY_THRESHOLD for this path-shaped content.
        let content = "auth config lives in abc12345/de678901/fa234567.md";
        assert!(
            check(content).is_ok(),
            "scattered short hex runs that never sum to a credential length \
             must stay allowed: fired {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_fp_paths_whose_full_token_entropy_is_already_below_threshold() {
        // 4 of the 7 original FP-repro paths stay OK near a trigger word even
        // with NO structured-identifier exemption at all, because their own
        // full-token Shannon entropy already reads below ENTROPY_THRESHOLD
        // (4.5) — the exemption was never load-bearing for these regardless
        // of which version of it existed.
        let paths = [
            "release_notes_v2.md",
            "docs/adr/ADR-055-epistemic-edge-relations.md",
            "crates/khive-pack-session/src/mirror/ingest.rs",
            "check_entropy_heuristic_impl",
        ];
        for p in paths {
            let content = format!("api_key handling in {p}");
            assert!(
                check(&content).is_ok(),
                "{p} must stay allowed near 'api_key' (full-token entropy already \
                 below threshold): fired {:?}",
                scan(&content)
            );
        }
    }

    #[test]
    fn allows_adr_draft_path_near_trigger() {
        let content = "api_key handling in fable-ops/ADR-DRAFT-adr079-slices234.md";
        assert!(
            check(content).is_ok(),
            "ADR-DRAFT path in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_workspace_packet_path_near_trigger() {
        let content = "api_key handling in internal/workspaces/20260701/adr079-slices234/PACKET.md";
        assert!(
            check(content).is_ok(),
            "workspace path in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_high_entropy_repo_audit_path_near_api_key() {
        let content =
            "api_key handling in internal/workspaces/20260701/cloud-rebuild/R1-repo-audit.md";
        assert!(
            check(content).is_ok(),
            "repository path in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_source_paths_near_ordinary_key_and_token_prose() {
        let contents = [
            "see <a/path/to/file.py>:~97-103 lists it as a real checkpoint-supplied key",
            "see <a/path/to/file.py>:~97-103 emits one extra token",
            "see /workspace/src/checkpoint_loader.rs:97-103\n\nconfiguration key behavior",
            "the token behavior is implemented in src/runtime/secret_gate.rs:618-914.",
        ];
        for content in contents {
            assert!(
                check(content).is_ok(),
                "source path in technical prose must pass: {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn allows_adr_authorization_path_in_markdown_ingest() {
        let content =
            "- Evidence: `docs/adr/C-ADR-007-authorization-server.md:70` defines token handling.";
        assert!(
            check(content).is_ok(),
            "ADR path citation in technical markdown must pass: got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_markdown_ingest_bare_opaque_value_near_token() {
        let content = concat!(
            "- Review evidence for token handling: ",
            "Xk9mZ2vQpLrT8nJwYuAeHfBs",
            "DcGiONvM1qPrStUvWxYz23456789"
        );
        assert_eq!(
            scan(content).map(|matched| matched.detector),
            Some("high-entropy-token"),
            "bare opaque value near token must remain blocked"
        );
    }

    // ── UUID / content-hash allowlists are prose-context only ───────────────

    #[test]
    fn blocks_uuid_directly_labeled_as_api_key() {
        let content = "api_key 550e8400-e29b-41d4-a716-446655440000";
        assert!(
            check(content).is_err(),
            "UUID-shaped token labeled api_key must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_sha256_content_hash_labeled_as_secret() {
        let content = "secret sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq";
        assert!(
            check(content).is_err(),
            "sha256-prefixed hash labeled secret must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_sha384_content_hash_labeled_as_api_key() {
        let content =
            "api_key sha384-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
        assert!(
            check(content).is_err(),
            "sha384-prefixed hash labeled api_key must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_sha512_content_hash_labeled_as_auth() {
        let content = "auth sha512-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ABCDEFGHIJKLMNOPQRSTUV";
        assert!(
            check(content).is_err(),
            "sha512-prefixed hash labeled auth must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_uuid_with_no_trigger_within_window() {
        // Common benign shape: a UUID (e.g. an internal record id) with no
        // credential trigger word anywhere in the surrounding window stays
        // allowed — the allowlist still applies outside trigger context.
        let content =
            "task 550e8400-e29b-41d4-a716-446655440000 was created and assigned to the team";
        assert!(
            check(content).is_ok(),
            "UUID with no nearby trigger word must stay allowed; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_area_id_uuid_near_authorized_substring() {
        // An internal task `area_id` UUID field sitting within the trigger
        // window of the SUBSTRING "auth" inside
        // `authorized_write_requires_dominance` is not a genuine mention of
        // the word "auth": it is a pure substring collision with
        // "authorized". Bare trigger words match at a word boundary (see
        // `contains_bounded_word`), so `auth` does not match inside
        // `authorized`; this UUID has no trigger in its window and passes via
        // the ordinary out-of-context UUID allowlist.
        let content = "area_id: cfcea31d-6f50-4fd1-ad6d-5f160de1694c\n\n## Problem\nReduce Lion microkernel axioms. Converted authorized_write_requires_dominance from axiom to theorem.";
        assert!(
            check(content).is_ok(),
            "internal area_id UUID near the 'authorized' substring \
             (not a genuine 'auth' mention) must now pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_uuid_on_line_after_benign_token_contract_title() {
        let content = "Design language and token contract\n550e8400-e29b-41d4-a716-446655440000";
        assert!(
            check(content).is_ok(),
            "a generic token-contract title must not make a next-line UUID look like a secret; \
             got {:?}",
            scan(content)
        );
    }

    #[test]
    fn generic_token_uuid_exemption_keeps_strong_credential_controls() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let uuid = "550e8400-e29b-41d4-a716-446655440000";
        let cases = [
            (format!("service token {opaque}"), "high-entropy-token"),
            (format!("token={opaque}"), "high-entropy-token"),
            (format!("token={uuid}"), "uuid-near-trigger"),
            (format!("api_key {uuid}"), "uuid-near-trigger"),
        ];

        for (content, detector) in cases {
            assert_eq!(
                scan(&content).map(|matched| matched.detector),
                Some(detector),
                "credential-shaped control must remain blocked: {content:?}"
            );
        }
    }

    // ── UUID/hash value extraction from assignment and wrapper syntax ───────

    #[test]
    fn blocks_uuid_glued_to_assignment_equals() {
        let content = "api_key=550e8400-e29b-41d4-a716-446655440000";
        assert!(
            check(content).is_err(),
            "UUID glued via '=' to a trigger word must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_with_trailing_sentence_period() {
        let content = "api_key 550e8400-e29b-41d4-a716-446655440000.";
        assert!(
            check(content).is_err(),
            "UUID with a trailing sentence period near a trigger must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_wrapped_in_parens() {
        let content = "api_key (550e8400-e29b-41d4-a716-446655440000)";
        assert!(
            check(content).is_err(),
            "UUID wrapped in parens near a trigger must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_in_json_object() {
        let content = "{\"api_key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
        assert!(
            check(content).is_err(),
            "UUID in a JSON-ish object near a trigger key must be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_content_hash_glued_to_assignment_equals() {
        let content = "secret=sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq";
        assert!(
            check(content).is_err(),
            "sha256-prefixed hash glued via '=' to a trigger word must be blocked; \
             got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_content_hash_with_trailing_sentence_period() {
        let content = "secret sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq.";
        assert!(
            check(content).is_err(),
            "sha256-prefixed hash with a trailing period near a trigger must be \
             blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_content_hash_wrapped_in_parens() {
        let content = "secret (sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq)";
        assert!(
            check(content).is_err(),
            "sha256-prefixed hash wrapped in parens near a trigger must be blocked; \
             got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_content_hash_in_json_object() {
        let content = "{\"secret\":\"sha256-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq\"}";
        assert!(
            check(content).is_err(),
            "sha256-prefixed hash in a JSON-ish object near a trigger key must be \
             blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_uuid_wrapped_in_parens_with_no_trigger_nearby() {
        // Control: the prose allowlist must survive for wrapper syntax when
        // there is no credential trigger word anywhere in the window — only
        // the trigger-context extraction changed, not the outside-context
        // allowlist itself.
        let content = "wrapper (550e8400-e29b-41d4-a716-446655440000) present";
        assert!(
            check(content).is_ok(),
            "UUID wrapped in parens with no trigger word nearby must stay allowed; \
             got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_padded_content_hash_glued_to_assignment_with_trailing_period() {
        // A padded base64 value ends in its own `=`, which is also a valid
        // separator character — `value_candidates` must enumerate the
        // suffix after every `=`/`:`, not assume any single separator
        // position, so the true value is recovered regardless of which
        // separator happens to sit where.
        let content = "secret=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
        assert!(
            check(content).is_err(),
            "padded sha256 hash glued via '=' with a trailing period must be \
             blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_padded_content_hash_in_json_object() {
        let content = "{\"secret\":\"sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=\"}";
        assert!(
            check(content).is_err(),
            "padded sha256 hash in a JSON-ish object near a trigger key must be \
             blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_when_json_label_itself_contains_colon() {
        // The label can itself contain the separator character
        // (`"api:key"` rather than `"api_key"`); the first `:` after
        // wrapper-stripping then lands inside the label, not at the
        // label/value boundary. value_candidates must still surface the
        // bare UUID as a later suffix candidate.
        let content = "{\"api:key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
        assert!(
            check(content).is_err(),
            "UUID must be blocked even when the JSON label contains ':'; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_when_json_label_itself_contains_equals() {
        let content = "{\"api=key\":\"550e8400-e29b-41d4-a716-446655440000\"}";
        assert!(
            check(content).is_err(),
            "UUID must be blocked even when the JSON label contains '='; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_uuid_behind_doubled_assignment() {
        // key=label=value: the first `=` lands between two labels, not at
        // the true value boundary.
        let content = "api_key=label=550e8400-e29b-41d4-a716-446655440000"; // gitleaks:allow
        assert!(
            check(content).is_err(),
            "UUID must be blocked behind a doubled assignment; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_padded_content_hash_behind_doubled_assignment_equals() {
        let content = "secret=label=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
        assert!(
            check(content).is_err(),
            "padded content hash must be blocked behind a doubled '=' assignment; \
             got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_padded_content_hash_behind_doubled_assignment_colon() {
        let content = "secret:label=sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=.";
        assert!(
            check(content).is_err(),
            "padded content hash must be blocked behind a doubled ':'+'=' \
             assignment; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn allows_benign_url_with_scheme_and_path_separators() {
        // `value_candidates`'s any-suffix semantics must not block ordinary
        // URLs, whose `://` and `/` characters produce several suffix
        // candidates but none of them are UUID- or content-hash-shaped.
        // Placed near a real trigger word ("key") so the check actually
        // exercises the trigger-context path rather than being skipped
        // outright.
        let content = "api_key endpoint=https://example.test/resource/for/testing";
        assert!(
            check(content).is_ok(),
            "a benign URL near a trigger word must stay allowed; got {:?}",
            scan(content)
        );
    }

    // ── Trigger word-boundary matching ──────────────────────────────────────

    #[test]
    fn allows_trigger_substrings_inside_benign_path_slugs() {
        let paths = [
            "docs/_archive/adr_v0/ADR-051-cli-auth-and-kg-git-workflow.md",
            "docs/platform/oauth-callback-docs-and-redirect-handling-v2.md",
            "docs/research/author-attribution-and-collaboration-notes.md",
            "docs/security/passwordless-authentication-overview-v3.md",
            "docs/platform/private_keynote-authoring-guide-v2.md",
        ];
        for path in paths {
            assert!(
                check(path).is_ok(),
                "trigger substring inside a benign path slug must not make the path \
                 its own credential context: {path:?}, got {:?}",
                scan(path)
            );
        }
    }

    #[test]
    fn blocks_inline_auth_assignment_with_high_entropy_value() {
        let content = "auth=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        assert!(
            check(content).is_err(),
            "auth=<high-entropy-value> must still be blocked; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_suffix_bearing_compound_credential_assignments() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let cases = [
            format!("api_keyv2={opaque}"),
            format!("access_keyv2={opaque}"),
            format!("private_keyv2={opaque}"),
            format!("API_KEYV2={opaque}"),
            format!(r#"{{"private_keyv2":"{opaque}"}}"#),
        ];
        for content in &cases {
            assert!(
                check(content).is_err(),
                "suffix-bearing compound credential assignment must be blocked: \
                 {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_spaced_suffix_bearing_compound_credential_assignments() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        for label in ["api_keyv2", "access_keyv2", "private_keyv2"] {
            let cases = [
                format!("{label} = {opaque}"),
                format!("{label} : {opaque}"),
                format!(r#"{{"{label}": "{opaque}"}}"#),
            ];
            for content in &cases {
                assert!(
                    check(content).is_err(),
                    "spaced suffix-bearing compound credential assignment must be \
                     blocked: {content:?}, got {:?}",
                    scan(content)
                );
            }
        }
    }

    #[test]
    fn blocks_suffix_bearing_compound_credentials_without_assignment_separator() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        for label in ["api_keyv2", "access_keyv2", "private_keyv2"] {
            let cases = [format!("{label} {opaque}"), format!("{label}{opaque}")];
            for content in &cases {
                assert!(
                    check(content).is_err(),
                    "suffix-bearing compound credential without an assignment separator must be \
                     blocked: {content:?}, got {:?}",
                    scan(content)
                );
                assert!(
                    mask_secrets(content).contains(REDACTION_MARKER),
                    "shared secret masker must redact separator-free compound credential: \
                     {content:?}"
                );
            }
        }

        let prefixed = "xapi_keyv2=Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        assert!(
            check(prefixed).is_err(),
            "prefix-bearing compound credential assignment must be blocked: \
             {prefixed:?}, got {:?}",
            scan(prefixed)
        );
    }

    #[test]
    fn allows_authorized_and_authentication_prose_near_uuid() {
        // The word-boundary fix directly: "auth" no longer matches the
        // substring inside "authorized"/"authentication", so ordinary prose
        // using those words does not poison the trigger window for a nearby
        // UUID or other allowlisted shape.
        let cases = [
            "authorized_write_requires_dominance was converted from axiom to theorem, id 550e8400-e29b-41d4-a716-446655440000",
            "authentication flow diagram lives at 550e8400-e29b-41d4-a716-446655440000",
        ];
        for content in cases {
            assert!(
                check(content).is_ok(),
                "'authorized'/'authentication' substring must not trigger the \
                 entropy heuristic: {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn allows_turkey_monkey_keyword_prose_near_uuid() {
        // Other bare-word substring collisions in TRIGGER_WORDS ("key") must
        // likewise not fire on ordinary English words that merely contain it.
        let cases = [
            "the turkey and monkey story references id 550e8400-e29b-41d4-a716-446655440000",
            "keyword research doc: 550e8400-e29b-41d4-a716-446655440000",
        ];
        for content in cases {
            assert!(
                check(content).is_ok(),
                "'turkey'/'monkey'/'keyword' substring must not trigger the \
                 entropy heuristic: {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn blocks_opaque_tokens_near_standalone_trigger_words() {
        // Word-boundary matching only removes SUBSTRING collisions; a genuine
        // standalone trigger word must still dominate exactly as before.
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let cases = [
            format!("auth header {opaque}"),
            format!("the key is {opaque}"),
            format!("secret value: {opaque}"),
        ];
        for content in &cases {
            assert!(
                check(content).is_err(),
                "a genuine standalone trigger word must still block: {content:?}, \
                 got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn issue_2654_lookup_members_accept_record_references() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        for label in [
            "association_key",
            "partition_key",
            "sort_key",
            "cache_key",
            "idempotency_key",
            "primary_key",
        ] {
            for value in [id, "", "runtime/current", "record-slug"] {
                for separator in [",", ", "] {
                    let content = format!(r#"{{"{label}":"{value}"{separator}"neighbor":"{id}"}}"#);
                    assert!(check(&content).is_ok(), "{content}: {:?}", check(&content));
                    assert_eq!(mask_secrets(&content), content);
                }
            }
        }
        let renamed = format!(r#"{{"association_ref":"{id}","neighbor":"{id}"}}"#);
        assert!(check(&renamed).is_ok());
    }

    #[test]
    fn issue_2654_credential_compounds_and_natural_assignments_stay_refused() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        for label in [
            "key",
            "api_key",
            "secret_key",
            "private_key",
            "access_key",
            "signing_key",
            "encryption_key",
            "auth_key",
            "service_signing_key",
        ] {
            for content in [
                format!("{label}={id}"),
                format!("{label}: {id}"),
                format!(r#"{{"{label}":"{id}"}}"#),
            ] {
                assert!(check(&content).is_err(), "{content}");
                assert!(!mask_secrets(&content).contains(id), "{content}");
            }
        }
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        for content in [
            format!("the key is {opaque}"),
            format!("api key {opaque}"),
            format!("association_key {id}"),
            format!("_key_ = {id}"),
            format!("association_key=x key={id}"),
        ] {
            assert!(check(&content).is_err(), "{content}");
        }
        assert!(check("secret docs/guide.md").is_ok());
        assert!(check("auth release-slug").is_ok());
    }

    #[test]
    fn issue_2654_lookup_exception_requires_an_assignment_gap() {
        let id = "550e8400-e29b-41d4-a716-446655440000";
        for gap in ["***", ")", "}", "\\", "!", " ", "\" "] {
            let content = format!("association_key{gap}:{id}");
            assert!(check(&content).is_err(), "{content}");
            assert!(!mask_secrets(&content).contains(id), "{content}");
        }
        for gap in ["", "\"", "'", "`"] {
            let content = format!("association_key{gap}:{id}");
            assert!(check(&content).is_ok(), "{content}");
        }
    }

    #[test]
    fn issue_2654_repeated_key_identifier_is_scanned_once() {
        let content = format!("{}key=x", "key_".repeat(262_144));
        assert!(check(&content).is_ok());
    }

    #[test]
    fn issue_2654_unicode_before_lookup_member_keeps_boundaries() {
        let content = "記録association_key: 550e8400-e29b-41d4-a716-446655440000";
        assert!(check(content).is_ok(), "{:?}", check(content));
    }

    #[test]
    fn issue_2654_unlisted_key_compounds_stay_credential_labels() {
        // The lookup exception is a closed allowlist: a `*_key` label it does
        // not name keeps `key` as a credential trigger for every value shape.
        let hex = "0123456789abcdef".repeat(4);
        let id = "550e8400-e29b-41d4-a716-446655440000";
        let neighbor = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        for label in [
            "hmac_key",
            "master_key",
            "ssh_key",
            "jwt_key",
            "webhook_key",
            "license_key",
            "gpg_key",
            "service_key",
            "client_key",
            "service_hmac_key",
        ] {
            for value in [hex.as_str(), id, opaque] {
                for content in [
                    format!("{label}={value}"),
                    format!("{label}: {value}"),
                    format!(r#"{{"{label}":"{value}"}}"#),
                    format!(r#"{{"neighbor":"{neighbor}","{label}":"{value}"}}"#),
                ] {
                    assert!(check(&content).is_err(), "{content}");
                    assert!(!mask_secrets(&content).contains(value), "{content}");
                }
            }
        }
    }

    #[test]
    fn issue_2654_listed_lookup_labels_accept_identifier_shapes() {
        let hex = "0123456789abcdef".repeat(4);
        let id = "550e8400-e29b-41d4-a716-446655440000";
        for label in LOOKUP_KEY_LABELS {
            for value in [id, hex.as_str(), "runtime/current", "record-slug"] {
                for content in [
                    format!("{label}={value}"),
                    format!(r#"{{"{label}":"{value}","neighbor":"{id}"}}"#),
                ] {
                    assert!(check(&content).is_ok(), "{content}: {:?}", scan(&content));
                    assert_eq!(mask_secrets(&content), content);
                }
            }
        }
        // A credential word in the prefix is its own trigger.
        assert!(check(&format!("secret_partition_key={id}")).is_err());
        assert!(check(&format!("api_key_cache_key={id}")).is_err());
    }

    #[test]
    fn issue_2654_qualified_lookup_labels_stay_refused() {
        // The vocabulary matches whole labels. A prefix rule ("anything ending
        // in `_` before a listed suffix") re-opens exactly the compounds the
        // list closes, because stems such as `hmac` or `jwt` are not trigger
        // words of their own. The cost is that a qualified lookup spelling
        // (`left_association_key`) is refused too; that is the fail-closed side.
        let hex = "0123456789abcdef".repeat(4);
        let id = "550e8400-e29b-41d4-a716-446655440000";
        for label in [
            "hmac_cache_key",
            "master_routing_key",
            "jwt_lookup_key",
            "ssh_row_key",
            "webhook_search_key",
            "license_index_key",
            "left_association_key",
            "record_partition_key",
        ] {
            for content in [
                format!("{label}={hex}"),
                format!(r#"{{"{label}":"{hex}","neighbor":"{id}"}}"#),
            ] {
                assert!(check(&content).is_err(), "{content}");
                assert!(!mask_secrets(&content).contains(hex.as_str()), "{content}");
            }
        }
    }

    #[test]
    fn accepted_false_positive_workspace_artifact_path_behind_attributive_trigger() {
        // "secret gate false positive repro: <path>" carries a trigger word
        // in clause range ahead of a value delimiter. The clause walk no
        // longer caps content words after a delimiter (any cap re-admits the
        // chained-qualifier labeled-value bypass), so this meta-prose shape
        // blocks. Accepted false positive — same attributive-trigger class
        // as the auth-setup docs path; documented in docs/api/secret_gate.md.
        let content = "writing up the secret gate false positive repro: \
             .workspace/20260101/fix-secret-gate-trigger-false-positive/MEASUREMENT_REPORT.md";
        assert!(
            check(content).is_err(),
            "accepted-FP contract changed: attributive trigger before a \
             delimited path no longer blocks — update the docs if deliberate"
        );
    }

    #[test]
    fn accepted_false_positive_archive_doc_path_behind_attributive_trigger() {
        // "secret scanner archive notes: <path>" — attributive trigger two
        // qualifiers ahead of the delimiter. Same accepted-FP class as
        // above; the walk cannot tell an attributive trigger from a label
        // head without reopening the chained-qualifier bypass.
        let content =
            "secret scanner archive notes: docs/_archive/ADR051-TenantEncryption-v2Notes.md";
        assert!(
            check(content).is_err(),
            "accepted-FP contract changed: attributive trigger before a \
             delimited path no longer blocks — update the docs if deliberate"
        );
    }

    #[test]
    fn allows_absolute_path_near_standalone_auth() {
        let content = "the auth scanner flagged this file: /home/user/projects/workspace/SessionNotes20260107/AuthGateFollowup2.md";
        assert!(
            check(content).is_ok(),
            "absolute path in technical prose must pass; got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_assignment_shaped_credential_disguised_as_path_near_api_key() {
        // Adversarial negative: a credential-shaped value glued via '='
        // directly to a trigger word must not be exempted just because it is
        // path-shaped (separator-delimited, word-shaped runs) and looks
        // superficially like the technical paths above. The compound label
        // `api_key` makes this a credential value, so it must block.
        let content = "api_key=/home/user/workspaces/2026/topic-name-example/SECRET_VALUE_HERE.md";
        assert!(
            check(content).is_err(),
            "assignment-shaped credential disguised as a path must still be \
             blocked: {content:?}, got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_separator_split_secret_access_key_compound() {
        // Adversarial negative: a separator-split bypass shape must still be
        // blocked. The `secret` and `key` entries both match because underscore
        // is a boundary for bare `TRIGGER_WORDS`. This asserts the end-to-end
        // outcome.
        let content = "secret_access_key abcdefghij/klmnopqrst/uvwxyzabcd/efghijk.md";
        assert!(
            check(content).is_err(),
            "secret_access_key bypass shape must still be blocked: {content:?}, \
             got {:?}",
            scan(content)
        );
    }

    // ── Underscore is a BOUNDARY for bare TRIGGER_WORDS, not a continuation ─
    // Opposite of `has_standalone_token`'s rule for `token`: treating underscore as a
    // boundary here is what keeps `SECRET_KEY=`/`auth_token=`/`signing_key=` detected
    // (`contains_word`'s `underscore_is_word_char` parameter controls this per caller).

    #[test]
    fn blocks_secret_key_assignment_when_underscore_bounds_trigger() {
        // `SECRET_KEY=<value>` must block via the plain-substring `secret`
        // trigger even though `secret` is followed by `_` rather than a
        // non-word-char boundary.
        let content = "SECRET_KEY=dGhpc2lzYXNlY3JldGtleXZhbHVlMTIzNDU2Nzg5MA=="; // gitleaks:allow
        assert!(
            check(content).is_err(),
            "SECRET_KEY=<value> (Django/Flask-style config) must still be \
             blocked: {content:?}, got {:?}",
            scan(content)
        );
    }

    #[test]
    fn blocks_auth_token_assignment_when_underscore_bounds_trigger() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let content = format!("auth_token={opaque}");
        assert!(
            check(&content).is_err(),
            "auth_token=<value> must still be blocked: {content:?}, got {:?}",
            scan(&content)
        );
    }

    #[test]
    fn blocks_underscore_joined_session_secret_and_signing_key_compounds() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let cases = [
            format!("session_secret_{opaque}"),
            format!("signing_key={opaque}"),
        ];
        for content in &cases {
            assert!(
                check(content).is_err(),
                "underscore-joined credential compound must still be blocked: \
                 {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn allows_letter_joined_trigger_substrings_in_benign_prose() {
        // The letter-joined substring-collision exemption must survive the
        // underscore-as-boundary change, since that change only affects the
        // underscore character, not letter-joined words.
        let cases = [
            "authorized_write_requires_dominance was converted from axiom to theorem, id 550e8400-e29b-41d4-a716-446655440000",
            "authentication flow diagram lives at 550e8400-e29b-41d4-a716-446655440000",
            "the turkey and monkey story references id 550e8400-e29b-41d4-a716-446655440000",
            "keyword research doc: 550e8400-e29b-41d4-a716-446655440000",
        ];
        for content in cases {
            assert!(
                check(content).is_ok(),
                "letter-joined substring collision must stay exempt: \
                 {content:?}, got {:?}",
                scan(content)
            );
        }
    }

    #[test]
    fn block_message_carries_actionable_guidance() {
        let fake = "AKIAFAKEKEY1234567890";
        let m = scan(fake).unwrap();
        let rendered = m.to_string();
        assert!(
            rendered.contains("real credential"),
            "block message must carry actionable guidance: {rendered}"
        );
    }

    #[test]
    fn block_message_shape_guidance_names_effective_boundary() {
        let opaque = "Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvMabcdef"; // gitleaks:allow
        let content = format!("auth header {opaque}");
        let m = scan(&content).unwrap();
        let rendered = m.to_string();
        assert!(
            rendered.contains("sentence") || rendered.contains("paragraph"),
            "shape-based detector guidance must name an effective context boundary: {rendered}"
        );
    }
}

// ─── Corpus replay harness (manual, opt-in) ─────────────────────────────────
//
// Measures how many real note/entity strings the gate blocks, so a detector
// change can be evaluated against production content rather than intuition
// (see the module doc). Opens the target database
// STRICTLY read-only (`SQLITE_OPEN_READ_ONLY`) and never mutates it. Point
// `KHIVE_REPLAY_DB` at a copy or a live KG database file path; the harness
// never writes, locks aggressively, or deletes anything.
//
// Run with: `KHIVE_REPLAY_DB=/path/to/khive.db cargo test -p khive-runtime \
//   --release -- --ignored --nocapture corpus_replay`
#[cfg(test)]
mod corpus_replay {
    use super::*;
    use rusqlite::{Connection, OpenFlags};

    // ── Whole-token-average entropy dilution (issue #1044, false-negative) ──

    #[test]
    fn blocks_hex_credential_diluted_by_filler_path_segments() {
        // A real 40-char hex credential as one path segment among low-entropy
        // filler segments. Whole-token-average entropy is diluted below
        // ENTROPY_THRESHOLD, and the whole token is not pure hex (it has `/`
        // and `.` in it), so neither the whole-token entropy check nor the
        // whole-token hex-credential-token check catches it — only a per-run
        // check does.
        let line = "api key vault/9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c/rotate.md";
        let m = scan(line);
        assert!(
            m.is_some(),
            "hex credential diluted by filler path segments must be blocked; got None"
        );
        assert_eq!(m.unwrap().detector, "hex-credential-token");
    }

    #[test]
    fn blocks_chopped_secret_padded_by_filler_runs() {
        // A random high-entropy run planted among short filler runs. Whole-
        // token-average entropy is diluted below threshold by the filler.
        let line = "secret path a/b/c/d/Xk9mZ2vQpLrT8nJwYuAeHfBsDcGiONvM/e/f.rs"; // gitleaks:allow
        let m = scan(line);
        assert!(
            m.is_some(),
            "chopped/padded secret among filler runs must be blocked; got None"
        );
        assert_eq!(m.unwrap().detector, "high-entropy-token");
    }

    #[test]
    fn allows_real_paths_with_no_run_reaching_min_entropy_len() {
        // Regression guard: the #1040 measurement corpus's real path false
        // positives never contain a single run >= MIN_ENTROPY_LEN, so the new
        // per-run check introduced for #1044 must not newly block them.
        let contents = [
            "branch feat-session-mirror pushed, see release_notes_v2.md for the key findings",
            "password reset doc: docs/adr/ADR-055-epistemic-edge-relations.md",
            "credential handling code crates/khive-pack-session/src/mirror/ingest.rs",
            "api key handling lives in check_entropy_heuristic_impl",
        ];
        for content in contents {
            assert!(
                check(content).is_ok(),
                "real path with no long run must still pass; fired: {:?}",
                scan(content)
            );
        }
    }

    #[test]
    #[ignore]
    fn replay_against_corpus() {
        let db_path = std::env::var("KHIVE_REPLAY_DB")
            .expect("set KHIVE_REPLAY_DB=/path/to/khive.db to run the corpus replay (read-only)");
        let conn = Connection::open_with_flags(
            &db_path,
            OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
        )
        .expect("open corpus DB read-only");

        let mut total = 0usize;
        let mut blocked = 0usize;
        let mut samples: Vec<String> = Vec::new();

        let mut collect = |sql: &str| {
            let mut stmt = conn.prepare(sql).expect("prepare replay query");
            let mut rows = stmt.query([]).expect("query replay rows");
            while let Some(row) = rows.next().expect("read replay row") {
                let content: Option<String> = row.get(0).unwrap_or(None);
                let Some(content) = content else { continue };
                if content.is_empty() {
                    continue;
                }
                total += 1;
                if let Some(m) = scan(&content) {
                    blocked += 1;
                    if samples.len() < 30 {
                        samples.push(format!(
                            "{} :: {}",
                            m,
                            content.chars().take(160).collect::<String>()
                        ));
                    }
                }
            }
        };

        collect("SELECT content FROM notes WHERE deleted_at IS NULL");
        collect("SELECT description FROM entities WHERE deleted_at IS NULL");

        eprintln!("corpus replay: {blocked}/{total} strings blocked");
        for s in &samples {
            eprintln!("  BLOCKED: {s}");
        }
    }

    /// Generates the sanitized corpus manifest at
    /// `tests/data/secret_gate_corpus_manifest.md`: per-detector block counts plus a
    /// sha256 of each blocked candidate, never the candidate text itself. Point-in-time
    /// generator, not a CI check — re-run manually (`KHIVE_REPLAY_DB=... cargo test -p
    /// khive-runtime --release -- --ignored --nocapture generate_corpus_manifest`) and
    /// hand-update the checked-in file when the detector set changes.
    #[test]
    #[ignore]
    fn generate_corpus_manifest() {
        use sha2::{Digest, Sha256};
        use std::collections::BTreeMap;

        let db_path = std::env::var("KHIVE_REPLAY_DB")
            .expect("set KHIVE_REPLAY_DB=/path/to/khive.db to run the corpus replay (read-only)");
        let conn = Connection::open_with_flags(
            &db_path,
            OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
        )
        .expect("open corpus DB read-only");

        let mut total = 0usize;
        let mut counts_by_detector: BTreeMap<&'static str, usize> = BTreeMap::new();
        let mut hashes_by_detector: BTreeMap<&'static str, Vec<String>> = BTreeMap::new();
        let mut max_run_reaching_min_entropy_len = 0usize;

        let mut collect = |sql: &str| {
            let mut stmt = conn.prepare(sql).expect("prepare replay query");
            let mut rows = stmt.query([]).expect("query replay rows");
            while let Some(row) = rows.next().expect("read replay row") {
                let content: Option<String> = row.get(0).unwrap_or(None);
                let Some(content) = content else { continue };
                if content.is_empty() {
                    continue;
                }
                total += 1;
                // Track the #1040 soundness claim directly against the same
                // corpus this replay scans: the longest run any path-shaped
                // token contributes, so the "no real path false positive
                // reaches MIN_ENTROPY_LEN" claim is checked against actual
                // data rather than asserted.
                for token in content.split_whitespace() {
                    for run in token.split(|c: char| !c.is_ascii_alphanumeric()) {
                        max_run_reaching_min_entropy_len =
                            max_run_reaching_min_entropy_len.max(run.len());
                    }
                }
                if let Some(m) = scan(&content) {
                    *counts_by_detector.entry(m.detector).or_insert(0) += 1;
                    let hash = format!("{:x}", Sha256::digest(content.as_bytes()));
                    hashes_by_detector.entry(m.detector).or_default().push(hash);
                }
            }
        };

        collect("SELECT content FROM notes WHERE deleted_at IS NULL");
        collect("SELECT description FROM entities WHERE deleted_at IS NULL");

        let blocked: usize = counts_by_detector.values().sum();
        println!("total_scanned: {total}");
        println!("total_blocked: {blocked}");
        println!("longest_alphanumeric_run_in_corpus: {max_run_reaching_min_entropy_len}");
        println!("counts_by_detector:");
        for (detector, count) in &counts_by_detector {
            println!("  {detector}: {count}");
        }
        println!("blocked_content_sha256_by_detector:");
        for (detector, hashes) in &hashes_by_detector {
            println!("  {detector}:");
            for hash in hashes {
                println!("    {hash}");
            }
        }
    }
}