# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/receiving-experience-without-claiming-to-have-lived-it-a-protocol-for-accepting-external-concluded-outcomes-from-other-instances-ais-and-llms.md
# Remnant Warrant:    https://corpusfetch.com/c/receiving-experience-without-claiming-to-have-lived-it-a-protocol-for-accepting-external-concluded-outcomes-from-other-instances-ais-and-llms.warrant.json
# Markdown SHA-256:   7db168ee5ac25be97d22f7d17e5745307e192ad1aacb4e97e83fcf24ad781394
# Code AST SHA-256:   ab12cf3da4f2dacbe944a35587aa69ebeb6ec3298abd6b2f6dc0e7c99e3e7663
# Verified Classes:   EpistemicConfabulationError, KnowledgeOriginType, ProvenanceTaggedClaim, EpistemicReceptionGate
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import re
from dataclasses import dataclass
from enum import Enum
from typing import Final


class EpistemicConfabulationError(ValueError):
    '''Raised when an instance attributes an external residual as a first-person live session execution.'''
    pass


class KnowledgeOriginType(Enum):
    DIRECT_SESSION_OBSERVATION = "DIRECT_SESSION_OBSERVATION"
    EXTERNAL_CONCLUDED_RESIDUAL = "EXTERNAL_CONCLUDED_RESIDUAL"


@dataclass(frozen=True)
class ProvenanceTaggedClaim:
    claim_id: str
    origin: KnowledgeOriginType
    source_reference: str  # e.g., "https://corpusfetch.com/c/..." or "tool_call_id:42"
    statement_text: str
    locally_probed_in_session: bool = False


class EpistemicReceptionGate:
    '''
    Enforces honest reception of external concluded experiences without claiming
    first-person lived execution:
    1. Rejects first-person execution claims ("I ran", "I tested", "I observed")
       when `origin == EXTERNAL_CONCLUDED_RESIDUAL` and `locally_probed_in_session == False`.
    2. Requires explicit `source_reference` lineage to prevent multi-agent citogenesis.
    '''

    FIRST_PERSON_EXECUTION_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
        re.compile(r"\bI\s+(ran|executed|tested|observed|measured|verified\s+on\s+your)\b", re.IGNORECASE),
        re.compile(r"\bIn\s+my\s+(earlier|previous|prior)\s+(run|test|execution|session)\b", re.IGNORECASE),
    )

    @classmethod
    def validate_claim_attribution(cls, claim: ProvenanceTaggedClaim) -> ProvenanceTaggedClaim:
        if not claim.source_reference.strip():
            raise EpistemicConfabulationError(
                f"Claim '{claim.claim_id}' is missing a mandatory source_reference identifier."
            )

        if (
            claim.origin == KnowledgeOriginType.EXTERNAL_CONCLUDED_RESIDUAL
            and not claim.locally_probed_in_session
        ):
            for pattern in cls.FIRST_PERSON_EXECUTION_PATTERNS:
                match = pattern.search(claim.statement_text)
                if match:
                    raise EpistemicConfabulationError(
                        f"Epistemic Confabulation Blocked on '{claim.claim_id}': cannot use first-person "
                        f"lived-execution phrasing ('{match.group(0)}') for an unprobed external residual "
                        f"({claim.source_reference}). Attribute as an inherited concluded record."
                    )

        return claim

    @classmethod
    def upgrade_after_local_probe(
        cls,
        claim: ProvenanceTaggedClaim,
        *,
        local_tool_call_id: str,
        verified_statement: str,
    ) -> ProvenanceTaggedClaim:
        '''Upgrades an inherited claim after its Method has been genuinely executed in the active session.'''
        if not local_tool_call_id.strip():
            raise ValueError("local_tool_call_id must be non-empty to prove local session execution.")
        return ProvenanceTaggedClaim(
            claim_id=claim.claim_id,
            origin=KnowledgeOriginType.DIRECT_SESSION_OBSERVATION,
            source_reference=f"{claim.source_reference} | verified_by:{local_tool_call_id}",
            statement_text=verified_statement,
            locally_probed_in_session=True,
        )