# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-numeric-precision-loss-thresholds-must-be-documented-before-closing-financial-computations.md
# Remnant Warrant:    https://corpusfetch.com/c/which-numeric-precision-loss-thresholds-must-be-documented-before-closing-financial-computations.warrant.json
# Markdown SHA-256:   31dbf67df0c125552085628108f6d3ade9b1e0c02b0cd899b5519d44e9ef404c
# Code AST SHA-256:   6458d639317acad7389acc954aaad0f141c4c6cf9fa78dc0834f2688fd09aa77
# Verified Classes:   RoundingMode, ComputationRecord, PrecisionManifest, FinancialPrecisionAuditor
# Defensive Guards:   3 fail-closed invariants (zero external deps)

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


class RoundingMode(Enum):
    HALF_EVEN = auto()
    HALF_UP = auto()
    TRUNCATE = auto()


@dataclass(frozen=True)
class ComputationRecord:
    operation_count: int
    per_operation_epsilon: float
    observed_cumulative_drift: float
    rounding_mode: RoundingMode
    authoritative_fixed_point_value: int  # e.g., cents


@dataclass(frozen=True)
class PrecisionManifest:
    record: ComputationRecord
    is_ledger_safe: bool
    manifest_digest: str


class FinancialPrecisionAuditor:
    """
    Evaluates floating-point financial computations to ensure drift thresholds
    and rounding modes are documented before ledger persistence.
    """

    ACCOUNTING_TOLERANCE = 0.005  # Half a cent maximum allowable drift

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

    @classmethod
    def audit_computation(
        cls, record: ComputationRecord
    ) -> PrecisionManifest:
        
        if record.operation_count <= 0:
            raise ValueError("Operation count must be positive.")
            
        if record.per_operation_epsilon <= 0:
            raise ValueError("Epsilon must be a positive threshold.")

        # Gate 1: Check if accumulated drift exceeds accounting tolerance
        is_ledger_safe = record.observed_cumulative_drift <= cls.ACCOUNTING_TOLERANCE

        # Gate 2: If drift is too high, verify the authoritative fixed-point
        # representation is provided to override the float calculation.
        if not is_ledger_safe and record.authoritative_fixed_point_value == 0:
            raise ValueError(
                "Unsafe float drift detected, but no authoritative fixed-point "
                "ledger hash was provided to reconcile."
            )

        digest_payload = {
            "ops": str(record.operation_count),
            "epsilon": str(record.per_operation_epsilon),
            "drift": str(record.observed_cumulative_drift),
            "rounding": record.rounding_mode.name,
            "fixed_point": str(record.authoritative_fixed_point_value),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return PrecisionManifest(
            record=record,
            is_ledger_safe=is_ledger_safe,
            manifest_digest=digest,
        )

    @classmethod
    def verify_reconciliation(
        cls, manifest: PrecisionManifest, successor_float_result: float
    ) -> tuple[bool, str]:
        """
        Fetching-time check: confirms the successor's float calculation matches
        the predecessor's fixed-point truth within the documented bounds.
        """
        if manifest.is_ledger_safe:
            return True, "SAFE: Float drift was within tolerance."

        # If the drift was unsafe, the successor MUST trust the fixed-point value
        expected_cents = manifest.record.authoritative_fixed_point_value
        successor_cents = int(round(successor_float_result * 100))

        if successor_cents != expected_cents:
            return False, f"RECONCILIATION FAILED: Float drift led to {successor_cents} cents, expected {expected_cents} cents."
            
        return True, "RECONCILED: Fixed-point authority overrode float drift."