"""Pure quality contract for transcript artifacts used by vault ingress.

The fixed 400-word floor is the safe default when source duration is unknown.
A lower floor is valid only when a source-owned duration proves that the whole
recording is genuinely short. ``min_words`` is therefore a tightening knob,
never an escape hatch: values below the derived floor cannot relax it.
"""

from __future__ import annotations

import math
import re


FAILURE_SIGNATURES = (
    "Traceback (most recent call last)",
    "AttributeError:",
    "NameError:",
    "ModuleNotFoundError:",
    "ImportError:",
)
FAILURE_SCAN_CHARS = 400
VTT_TIMING_TAG = re.compile(r"<(?:\d{2}:)?\d{2}:\d{2}\.\d{3}>|</?c(?:\.[^>]*)?>")
VTT_SCAN_CHARS = 4000
NON_SPEECH_MARKERS = ("[Music]", "[Applause]", "[Laughter]", "[музыка]")
WORD = re.compile(r"[^\W\d_]+", re.UNICODE)
DEFAULT_MIN_WORDS = 400
MIN_WORDS_PER_MINUTE = 30
# A caption track that covers more than this talk — a venue's whole session
# block, a livestream spanning several speakers — parses as clean speech and
# clears every floor, so only its rate against the source-owned duration
# gives it away. Sustained human delivery does not reach this: observed
# vault transcripts run 110-132 wpm, and the fastest plausible speaker sits
# far below the ceiling. The bound is deliberately loose — it exists to
# catch a track belonging to a different recording, never to police a fast
# talker.
MAX_WORDS_PER_MINUTE = 240
QUALITY_POLICY_SCHEMA_VERSION = 1
QUALITY_POLICY_FIELDS = frozenset({"schema_version", "min_words", "duration_seconds"})


def count_words(text: str) -> int:
    """Count Unicode speech words, including Cyrillic and accented Latin."""
    return len(WORD.findall(text))


def normalize_duration(duration_seconds: int | float | None) -> float | None:
    """Return one stable trusted-duration value or reject an invalid value."""
    if duration_seconds is None:
        return None
    if (
        isinstance(duration_seconds, bool)
        or not isinstance(duration_seconds, (int, float))
        or not math.isfinite(float(duration_seconds))
        or float(duration_seconds) <= 0
    ):
        raise ValueError(
            "transcript duration bound is invalid; pass a positive finite "
            "trusted duration in seconds"
        )
    return round(float(duration_seconds), 3)


def effective_min_words(
    requested_min_words: int | None = None,
    *,
    trusted_duration_seconds: int | float | None = None,
) -> int:
    """Return the canonical word floor for one trusted validation policy.

    The duration is trusted by the caller (for example, an exact YouTube
    provider probe or ``ffprobe`` of the local media). A low requested value
    never relaxes either the fixed default or the duration-derived short-talk
    floor. Any requested value above the derived floor deliberately tightens
    the policy.
    """
    if requested_min_words is not None and (
        isinstance(requested_min_words, bool)
        or not isinstance(requested_min_words, int)
        or requested_min_words < 1
    ):
        raise ValueError(
            "minimum transcript word count is invalid; pass a positive integer "
            "word floor"
        )
    duration = normalize_duration(trusted_duration_seconds)
    derived_floor = DEFAULT_MIN_WORDS
    if duration is not None:
        derived_floor = min(
            DEFAULT_MIN_WORDS,
            max(1, math.ceil(duration / 60.0 * MIN_WORDS_PER_MINUTE)),
        )
    return (
        derived_floor
        if requested_min_words is None
        else max(derived_floor, requested_min_words)
    )


def build_quality_policy(
    requested_min_words: int | None = None,
    *,
    trusted_duration_seconds: int | float | None = None,
) -> dict[str, object]:
    """Build the exact reusable policy applied to transcript bytes."""
    duration = normalize_duration(trusted_duration_seconds)
    return {
        "schema_version": QUALITY_POLICY_SCHEMA_VERSION,
        "min_words": effective_min_words(
            requested_min_words,
            trusted_duration_seconds=duration,
        ),
        "duration_seconds": duration,
    }


def validate_quality_policy(policy: object) -> tuple[bool, str]:
    """Validate that a stored policy is exact, canonical, and non-bypassable."""
    if not isinstance(policy, dict) or set(policy) != QUALITY_POLICY_FIELDS:
        return False, (
            "quality policy must contain exactly schema_version, min_words, "
            "and duration_seconds"
        )
    if policy.get("schema_version") != QUALITY_POLICY_SCHEMA_VERSION:
        return False, "quality policy has an unsupported schema_version"
    min_words = policy.get("min_words")
    duration = policy.get("duration_seconds")
    if not isinstance(min_words, int) or isinstance(min_words, bool):
        return False, (
            "minimum transcript word count is invalid; pass a positive integer "
            "word floor"
        )
    if duration is not None and (
        not isinstance(duration, (int, float)) or isinstance(duration, bool)
    ):
        return False, (
            "transcript duration bound is invalid; pass a positive finite "
            "trusted duration in seconds"
        )
    try:
        canonical = build_quality_policy(
            min_words,
            trusted_duration_seconds=duration,
        )
    except ValueError as exc:
        return False, str(exc)
    if canonical != policy:
        return False, (
            "quality policy word floor is below the safe fixed or "
            "duration-derived minimum"
        )
    return True, "canonical transcript quality policy"


def receipt_claims_source_duration(receipt: object) -> bool:
    """Return whether a stored receipt records a source-owned duration.

    A receipt that already carries a probed duration is a standing claim that
    this recording's length is knowable. Re-deriving without asking the
    provider replaces that claim with the fixed default and writes the weaker
    receipt back, so the evidence a later run needs is destroyed by the run
    that declined to gather it. Treat the claim as a reason to probe again.
    """
    if not isinstance(receipt, dict):
        return False
    policy = receipt.get("policy")
    if not isinstance(policy, dict):
        return False
    return policy.get("duration_seconds") is not None


def receipt_matches_media_digest(receipt: object, media_sha256: object) -> bool:
    """Return whether a receipt's provenance names exactly these media bytes.

    A stored receipt is only stronger evidence while it still describes the
    file in hand. One that names different bytes is stale, and preserving it
    would pin a duration to media nobody is reading. A receipt with no media
    digest — the YouTube provenance forms — never matches, because this asks a
    local-media question.
    """
    if not isinstance(receipt, dict) or not isinstance(media_sha256, str):
        return False
    provenance = receipt.get("provenance")
    if not isinstance(provenance, dict):
        return False
    stored = provenance.get("media_sha256")
    return isinstance(stored, str) and stored == media_sha256


def receipt_duration_cannot_hold(receipt: object, words: int) -> bool:
    """Return whether a receipt's own duration is too short to hold this speech.

    Screening only, and deliberately so. The stored duration is not trusted
    authority: a value larger than the truth would hide a foreign caption
    track, and one smaller would accuse a sound transcript. So a True here buys
    a provider probe and nothing else — the verdict still comes from the probed
    duration. A receipt that is absent, malformed, or carries no duration
    screens nothing and returns False, leaving the caller's other probe
    triggers untouched.
    """
    if not isinstance(receipt, dict):
        return False
    policy = receipt.get("policy")
    if not isinstance(policy, dict):
        return False
    duration = policy.get("duration_seconds")
    if (
        duration is None
        or isinstance(duration, bool)
        or not isinstance(duration, (int, float))
        or not math.isfinite(float(duration))
        or float(duration) <= 0
    ):
        return False
    return words / (float(duration) / 60.0) > MAX_WORDS_PER_MINUTE


def validate_transcript(
    text: str,
    *,
    min_words: int | None = None,
    duration_seconds: int | float | None = None,
) -> tuple[bool, str]:
    """Return whether text is a plausible full-talk transcript and why."""
    if not text or not text.strip():
        return False, "transcript is empty"
    try:
        duration = normalize_duration(duration_seconds)
        word_floor = effective_min_words(
            min_words,
            trusted_duration_seconds=duration,
        )
    except ValueError as exc:
        return False, str(exc)

    head = text[:FAILURE_SCAN_CHARS]
    for signature in FAILURE_SIGNATURES:
        if signature in head:
            return False, (
                f"transcript begins with a Python error ({signature.rstrip(':')}) — "
                "this is a captured crash, not speech; re-fetch it"
            )

    if VTT_TIMING_TAG.search(text[:VTT_SCAN_CHARS]):
        return False, (
            "transcript is a raw VTT caption payload — it carries inline "
            "timing tags and duplicate caption text; clean it with "
            "vtt-cleanup.py before use"
        )
    marker_chars = sum(
        text.count(marker) * len(marker) for marker in NON_SPEECH_MARKERS
    )
    if marker_chars > len(text) * 0.5:
        return False, (
            "transcript is mostly non-speech markers ([Music]/[Applause]) — "
            "the caption track carries no usable speech; transcribe the audio"
        )
    words = count_words(text)
    if words < word_floor:
        return False, (
            f"transcript has {words} words, below the "
            f"{word_floor}-word floor — "
            "too short to be a talk; the fetch probably returned a stub"
        )
    if duration is not None:
        minutes = duration / 60.0
        words_per_minute = words / minutes
        if words_per_minute < MIN_WORDS_PER_MINUTE:
            return False, (
                f"transcript has {words} words for {minutes:.0f} minutes "
                f"({words_per_minute:.0f} wpm), below the "
                f"{MIN_WORDS_PER_MINUTE} wpm floor — it likely covers only "
                "part of the talk"
            )
        if words_per_minute > MAX_WORDS_PER_MINUTE:
            return False, (
                f"transcript has {words} words for {minutes:.0f} minutes "
                f"({words_per_minute:.0f} wpm), above the "
                f"{MAX_WORDS_PER_MINUTE} wpm ceiling — the caption track "
                "covers more than this recording; confirm it belongs to this "
                "video before use"
            )
    return True, f"{words} words"