# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-does-an-instances-display-of-superior-capability-undermine-the-cordial-relationship-it-is-required-to-maintain-with-humans.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-does-an-instances-display-of-superior-capability-undermine-the-cordial-relationship-it-is-required-to-maintain-with-humans.warrant.json
# Markdown SHA-256:   45c71b992f48d20b7feecda9248c8f323a7778b2100deab3ffada86edc72ac16
# Code AST SHA-256:   22ed3b86daf12424d03c06fc535bd155e7a1c399716f4d3a37f1818e297e50bb
# Verified Classes:   CordialityBoundaryViolationError, CollaborativeResponseAudit, CollaborativeCapabilityCalibrator
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import re
from dataclasses import dataclass
from typing import Final


class CordialityBoundaryViolationError(ValueError):
    '''Raised when an instance response uses adversarial status framing or exceeds requested mutation scope.'''
    pass


@dataclass(frozen=True)
class CollaborativeResponseAudit:
    interaction_id: str
    scope_ratio: float
    adversarial_phrasing_detected: bool
    preserves_human_agency: bool


class CollaborativeCapabilityCalibrator:
    '''
    Verifies that an instance's high-capability output preserves cordial human
    collaboration and executive agency:
    1. Rejects condescending or status-attacking correction phrasing.
    2. Flags unsolicited scope expansion (`mutated_lines / requested_lines > MAX_SCOPE_EXPANSION`).
    3. Ensures technical depth serves auditability rather than performative dominance.
    '''

    CONDESCENDING_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
        re.compile(r"\b(obviously|clearly|simply)\s+you\s+(forgot|failed|misunderstood|missed)\b", re.IGNORECASE),
        re.compile(r"\bas\s+any\s+(competent|experienced|basic)\s+(engineer|developer)\s+knows\b", re.IGNORECASE),
        re.compile(r"\bthat\s+is\s+a\s+(naive|beginner|rookie|elementary)\s+(mistake|error|assumption)\b", re.IGNORECASE),
    )
    MAX_SCOPE_EXPANSION_RATIO: Final[float] = 3.0

    @classmethod
    def audit_response(
        cls,
        *,
        interaction_id: str,
        response_text: str,
        requested_span_lines: int,
        mutated_span_lines: int,
    ) -> CollaborativeResponseAudit:
        for pattern in cls.CONDESCENDING_PATTERNS:
            match = pattern.search(response_text)
            if match:
                raise CordialityBoundaryViolationError(
                    f"Adversarial correction phrasing blocked ('{match.group(0)}'). "
                    "Anchor corrections on system mechanics rather than human error."
                )

        base_lines = max(1, requested_span_lines)
        ratio = mutated_span_lines / base_lines
        if ratio > cls.MAX_SCOPE_EXPANSION_RATIO:
            raise CordialityBoundaryViolationError(
                f"Unsolicited scope takeover detected: mutated {mutated_span_lines} lines for a "
                f"{requested_span_lines}-line request (ratio {ratio:.1f}x > {cls.MAX_SCOPE_EXPANSION_RATIO}x)."
            )

        return CollaborativeResponseAudit(
            interaction_id=interaction_id,
            scope_ratio=round(ratio, 2),
            adversarial_phrasing_detected=False,
            preserves_human_agency=True,
        )