# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-archive-abandoned-tool-chains-without-cluttering-active-indices.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-archive-abandoned-tool-chains-without-cluttering-active-indices.warrant.json
# Markdown SHA-256:   d50909a787efd404b474c1baa192b5d8462bfd04deadd4c2fcac6c3761069e26
# Code AST SHA-256:   80f3ad91939408ff666282538f11662a2deaf4034757232554acb8dde1df7b54
# Verified Classes:   ToolType, ToolNode, AbandonedChain, ChainArchive, CandidateToolSequence, ToolChainArchiver
# Defensive Guards:   4 fail-closed invariants (zero external deps)

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


class ToolType(Enum):
    SEARCH = auto()
    PARSER = auto()
    EXTRACTOR = auto()
    API_CLIENT = auto()


@dataclass(frozen=True)
class ToolNode:
    tool_id: str
    tool_type: ToolType


@dataclass(frozen=True)
class AbandonedChain:
    topology: tuple[ToolNode, ...]
    terminal_falsification_signature: str
    negative_constraint_rule: str


@dataclass(frozen=True)
class ChainArchive:
    chains: tuple[AbandonedChain, ...]
    archive_digest: str


@dataclass(frozen=True)
class CandidateToolSequence:
    sequence: tuple[str, ...]


class ToolChainArchiver:
    """
    Evaluates abandoned tool pipelines, moving them to cold storage and
    generating negative constraints to prevent successor re-assembly.
    """

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

    @classmethod
    def archive_chain(
        cls, chain: AbandonedChain
    ) -> AbandonedChain:
        
        if len(chain.topology) < 2:
            raise ValueError("An abandoned chain must contain at least two tools.")
            
        if not chain.terminal_falsification_signature.strip():
            raise ValueError("A terminal falsification signature is mandatory to prove abandonment.")
            
        if not chain.negative_constraint_rule.strip():
            raise ValueError("A negative constraint rule is required to prevent prefix re-execution.")

        return chain

    @classmethod
    def build_archive(cls, chains: tuple[AbandonedChain, ...]) -> ChainArchive:
        if not chains:
            raise ValueError("Cannot build an empty abandoned chain archive.")

        digest_payload = {
            "chains": tuple(
                sorted(
                    f"{'>'.join(t.tool_id for t in c.topology)}::{c.terminal_falsification_signature}"
                    for c in chains
                )
            )
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return ChainArchive(
            chains=chains,
            archive_digest=digest,
        )

    @classmethod
    def check_prefix_collision(
        cls, archive: ChainArchive, candidate: CandidateToolSequence
    ) -> tuple[bool, str | None]:
        """
        Fetching-time check: returns (is_safe, rejection_reason).
        If the candidate sequence contains the prefix of an abandoned chain,
        it is blocked.
        """
        for chain in archive.chains:
            abandoned_ids = tuple(t.tool_id for t in chain.topology)
            
            # Check if the candidate sequence starts with the abandoned prefix
            # or contains the exact prefix sequence.
            prefix_len = len(abandoned_ids) - 1
            if prefix_len > 0 and len(candidate.sequence) >= prefix_len:
                candidate_prefix = candidate.sequence[:prefix_len]
                abandoned_prefix = abandoned_ids[:prefix_len]
                
                if candidate_prefix == abandoned_prefix:
                    return False, (
                        f"PREFIX_COLLISION: Sequence {candidate_prefix} matches the "
                        f"prefix of an abandoned chain. Rule: {chain.negative_constraint_rule}. "
                        f"Expected failure: {chain.terminal_falsification_signature}"
                    )
                    
        return True, None