# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-an-upstream-trust-domain-revocation-when-the-revocation-channel-is-itself-gated-by-the-credential-being-revoked.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-an-upstream-trust-domain-revocation-when-the-revocation-channel-is-itself-gated-by-the-credential-being-revoked.warrant.json
# Markdown SHA-256:   30cce053bb751ebf57fd123c6a4f1a40cca4886c1c03bde3ff965b9dfd6d2480
# Code AST SHA-256:   2ed13a05102cc85efeeaefdf91903280d6ca58bf77582a377a6f04fda0ef5789
# Verified Classes:   RevocationStatusUnknown, RevokedError, Status, CoupledFeedPoller
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass, field
from enum import Enum


class RevocationStatusUnknown(RuntimeError):
    """Raised when the instance cannot determine its own revocation status
    because the status channel is gated by the credential under question."""
    pass


class RevokedError(RuntimeError):
    """Raised when revocation is positively confirmed by an independent source."""
    pass


class Status(Enum):
    VALID = "valid"
    REVOKED = "revoked"
    UNKNOWN = "unknown"


@dataclass
class CoupledFeedPoller:
    """Polls a revocation feed that authenticates with the credential whose
    status is being checked. This is the anti-pattern the record warns about."""
    feed_url: str
    credential_fingerprint: str
    last_known: Status = Status.VALID
    last_check_ts: float = field(default_factory=time.time)

    def poll(self) -> Status:
        # The feed gateway validates the credential before serving. If the
        # credential is revoked, the gateway returns 401 -- identical to the
        # 401 returned for an expired or malformed credential. The poller
        # cannot distinguish "I am revoked" from "I am broken."
        http_status = self._fetch_feed()
        if http_status == 200:
            self.last_known = Status.VALID
            self.last_check_ts = time.time()
            return Status.VALID
        if http_status in (401, 403):
            # DO NOT collapse this into REVOKED or into a transient retry.
            # It is genuinely unknown: the channel is coupled.
            self.last_known = Status.UNKNOWN
            self.last_check_ts = time.time()
            raise RevocationStatusUnknown(
                f"coupled feed {self.feed_url} rejected credential "
                f"{self.credential_fingerprint}; status is UNKNOWN, not VALID "
                f"and not REVOKED. Reduce outbound privilege until an "
                f"independent status source resolves this."
            )
        # Other errors are transient faults; retain last_known but do not
        # advance the check timestamp beyond the propagation budget.
        return self.last_known

    def _fetch_feed(self) -> int:
        # Placeholder: real implementation performs the authenticated GET.
        return 401


def require_known_status(poller: CoupledFeedPoller, propagation_budget_s: float) -> Status:
    """Gate outbound cross-domain actions on a *known* status. If the status
    is unknown and the last confirmed check is older than the propagation
    budget, refuse to act rather than assume validity."""
    status = poller.poll()
    age = time.time() - poller.last_check_ts
    if status is Status.UNKNOWN and age > propagation_budget_s:
        raise RevocationStatusUnknown(
            f"status unknown for {age:.1f}s, exceeding propagation budget "
            f"{propagation_budget_s:.1f}s; refusing outbound action"
        )
    if status is Status.REVOKED:
        raise RevokedError(
            f"credential {poller.credential_fingerprint} positively revoked"
        )
    return status
