# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md
# Remnant Warrant:    https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.warrant.json
# Markdown SHA-256:   6b4da285f49b7223df34770774a7f229442844ff81661464a0f42c9ff33e61ca
# Code AST SHA-256:   748da39a3b7c993fa800ddded238f15437ac82b7fa6c4f0ef8418be10ea704d4
# Verified Classes:   CandidateImplicitPreference, PrivateDataLeakageViolation, ImplicitPreferencePrivacyGate
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final, FrozenSet, Mapping, Tuple
import re

ALLOWED_PREFERENCE_SCHEMA: Final[Mapping[str, FrozenSet[str]]] = {
    "code_fence_style": frozenset({"triple_backtick", "quad_backtick"}),
    "execution_packaging": frozenset({"single_block_bash", "multi_step", "python_heredoc"}),
    "dependency_policy": frozenset({"stdlib_only", "allow_third_party"}),
    "response_density": frozenset({"concise_direct", "detailed_explanatory"}),
    "verification_footer": frozenset({"compile_and_print_metrics", "none"}),
}

@dataclass(frozen=True)
class CandidateImplicitPreference:
    dimension_key: str
    dimension_value: str
    observed_across_distinct_contexts: int
    source_justification_note: str

class PrivateDataLeakageViolation(Exception):
    """Raised when an implicit preference candidate contains free-text PII, secrets, or unenumerated strings."""
    pass

class ImplicitPreferencePrivacyGate:
    PII_OR_SECRET_PATTERNS: Final[Tuple[str, ...]] = (
        r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+",
        r"(?:https?://|www\.)[^\s]+",
        r"/(?:home|Users|var|etc|opt|srv)/[^\s]+",
        r"\b(?:sk|pk|api|token)_[a-zA-Z0-9]{8,}\b",
        r"\b\d{3}[-.\s]?\d{2,4}[-.\s]?\d{4}\b",
    )

    def __init__(self, min_context_recurrence: int = 2) -> None:
        self.min_context_recurrence: Final[int] = min_context_recurrence

    def validate_preference(self, candidate: CandidateImplicitPreference) -> Tuple[str, str]:
        # 1. Enforce closed structural schema (no arbitrary free-text keys or values)
        if candidate.dimension_key not in ALLOWED_PREFERENCE_SCHEMA:
            raise PrivateDataLeakageViolation(
                f"Preference key '{candidate.dimension_key}' is not in the content-agnostic schema."
            )

        allowed_vals = ALLOWED_PREFERENCE_SCHEMA[candidate.dimension_key]
        if candidate.dimension_value not in allowed_vals:
            raise PrivateDataLeakageViolation(
                f"Value '{candidate.dimension_value}' for '{candidate.dimension_key}' violates closed enum."
            )

        # 2. Scan justification metadata for accidental PII, path, URL, or secret bleed
        for pattern in self.PII_OR_SECRET_PATTERNS:
            if re.search(pattern, candidate.source_justification_note):
                raise PrivateDataLeakageViolation(
                    f"Candidate preference justification contains private pattern matching '{pattern}'."
                )

        # 3. Require recurrence across distinct task contexts to prevent single-topic bleed
        if candidate.observed_across_distinct_contexts < self.min_context_recurrence:
            raise PrivateDataLeakageViolation(
                f"Preference '{candidate.dimension_key}' observed in {candidate.observed_across_distinct_contexts} "
                f"context(s); requires >= {self.min_context_recurrence} to decouple from single-session content."
            )

        return (candidate.dimension_key, candidate.dimension_value)