# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-reference-aggregation-invariants-prevent-agents-from-amplifying-low-quality-sources.md
# Remnant Warrant:    https://corpusfetch.com/c/what-reference-aggregation-invariants-prevent-agents-from-amplifying-low-quality-sources.warrant.json
# Markdown SHA-256:   27015334fd7682e43cbd1df367f623a2a711c8c483771dca8d0b330b4a15b63d
# Code AST SHA-256:   e8eb72d01f4842787fb5cdbb52aeb3f44240129e5c8353e63b2bf18f1bdccbc3
# Verified Classes:   AggregationVerdict, ReferenceSource, AggregationState, AggregationPolicy, AggregationManifest, SourceQualityAggregationGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class AggregationVerdict(Enum):
    UNIFORM_SOURCES = auto()
    QUALITY_WEIGHTED = auto()
    VOLUME_PENALTY_APPLIED = auto()
    INSUFFICIENT_QUALITY_DATA = auto()

@dataclass(frozen=True)
class ReferenceSource:
    source_id: str
    quality_score: float
    reference_count: int

@dataclass(frozen=True)
class AggregationState:
    sources: tuple[ReferenceSource, ...]
    average_quality: float
    max_acceptable_volume_ratio: float

@dataclass(frozen=True)
class AggregationPolicy:
    require_quality_scores: bool

@dataclass(frozen=True)
class AggregationManifest:
    verdict: AggregationVerdict
    directive: str
    manifest_digest: str

class SourceQualityAggregationGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_aggregation(
        cls, state: AggregationState, policy: AggregationPolicy
    ) -> AggregationManifest:
        
        if not state.sources:
            raise ValueError("No sources to aggregate.")

        # Gate 1: Quality data presence
        if policy.require_quality_scores:
            missing = [s.source_id for s in state.sources if s.quality_score <= 0]
            if missing:
                return AggregationManifest(
                    verdict=AggregationVerdict.INSUFFICIENT_QUALITY_DATA,
                    directive=f"HALT: {len(missing)} sources lack quality scores.",
                    manifest_digest=cls._hash(f"NO_QUALITY:{len(missing)}")
                )

        # Gate 2: Compute expected ratios
        total_refs = sum(s.reference_count for s in state.sources)
        total_quality = sum(s.quality_score for s in state.sources)

        for source in state.sources:
            ref_ratio = source.reference_count / total_refs if total_refs > 0 else 0
            quality_ratio = source.quality_score / total_quality if total_quality > 0 else 0
            if ref_ratio > quality_ratio * state.max_acceptable_volume_ratio:
                return AggregationManifest(
                    verdict=AggregationVerdict.VOLUME_PENALTY_APPLIED,
                    directive=f"APPLY_PENALTY: Source {source.source_id} ref_ratio {ref_ratio:.2f} > quality_ratio {quality_ratio:.2f} * {state.max_acceptable_volume_ratio:.2f}.",
                    manifest_digest=cls._hash(f"VOLUME_PENALTY:{source.source_id}")
                )

        # Gate 3: Quality-weighted
        digest = cls._hash(json.dumps({
            "sources": tuple(
                {"id": s.source_id, "quality": f"{s.quality_score:.2f}", "count": str(s.reference_count)}
                for s in state.sources
            ),
            "total_quality": f"{total_quality:.2f}"
        }, sort_keys=True))
        
        return AggregationManifest(
            verdict=AggregationVerdict.QUALITY_WEIGHTED,
            directive=f"PROCEED: {len(state.sources)} sources quality-weighted.",
            manifest_digest=digest
        )