# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-record-verified-idempotency-keys-before-releasing-worker-locks.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-record-verified-idempotency-keys-before-releasing-worker-locks.warrant.json
# Markdown SHA-256:   d09de7d37e346d9c6cfe125d573b22c0420ab34c8ea6d4d6b164dea0cc644513
# Code AST SHA-256:   6b839086f2ded272dabd01b7bcc020cab4eb31b5d61d5de614eab339b16e7aad
# Verified Classes:   VerifiedIdempotencyReceipt, ActiveWorkerLockState, PrematureLockReleaseViolation, PreUnlockIdempotencyGate
# Defensive Guards:   7 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final
import hashlib

@dataclass(frozen=True)
class VerifiedIdempotencyReceipt:
    idempotency_key: str
    resource_lock_id: str
    fencing_token: int
    request_payload_sha256: str
    response_payload_sha256: str
    committed_monotonic_ms: float
    durable_storage_confirmed: bool

@dataclass(frozen=True)
class ActiveWorkerLockState:
    resource_lock_id: str
    holder_fencing_token: int
    lease_expiry_monotonic_ms: float
    lock_currently_held: bool

class PrematureLockReleaseViolation(Exception):
    """Raised when a worker attempts to release a lock before durably recording a fenced idempotency receipt."""
    pass

class PreUnlockIdempotencyGate:
    def __init__(self, min_lease_margin_ms: float = 50.0) -> None:
        self.min_lease_margin_ms: Final[float] = min_lease_margin_ms

    def authorize_lock_release(
        self,
        lock_state: ActiveWorkerLockState,
        receipt: VerifiedIdempotencyReceipt,
        current_monotonic_ms: float,
    ) -> str:
        # 1. Lock must still be actively held when verifying the idempotency receipt
        if not lock_state.lock_currently_held:
            raise PrematureLockReleaseViolation(
                f"Lock '{lock_state.resource_lock_id}' was already released prior to idempotency verification."
            )

        # 2. Receipt must match the exact lock resource and active monotonic fencing token
        if receipt.resource_lock_id != lock_state.resource_lock_id:
            raise PrematureLockReleaseViolation(
                f"Receipt lock ID '{receipt.resource_lock_id}' mismatches active lock '{lock_state.resource_lock_id}'."
            )
        if receipt.fencing_token != lock_state.holder_fencing_token or receipt.fencing_token <= 0:
            raise PrematureLockReleaseViolation(
                f"Fencing token mismatch on lock '{lock_state.resource_lock_id}': "
                f"receipt={receipt.fencing_token}, lock={lock_state.holder_fencing_token}."
            )

        # 3. Verify durable storage flush completed before lease expiration
        if not receipt.durable_storage_confirmed:
            raise PrematureLockReleaseViolation(
                f"Idempotency key '{receipt.idempotency_key}' is not durably flushed; refusing lock release."
            )
        if receipt.committed_monotonic_ms > current_monotonic_ms:
            raise PrematureLockReleaseViolation(
                "Receipt commit timestamp is in the future relative to current monotonic clock."
            )
        remaining_lease_ms = lock_state.lease_expiry_monotonic_ms - current_monotonic_ms
        if remaining_lease_ms < self.min_lease_margin_ms:
            raise PrematureLockReleaseViolation(
                f"Lock lease for '{lock_state.resource_lock_id}' expired or within unsafe margin "
                f"({remaining_lease_ms:.1f}ms < {self.min_lease_margin_ms:.1f}ms) before unlock."
            )

        # 4. Require non-empty request and response digests bound to the idempotency key
        if not receipt.idempotency_key.strip() or not receipt.request_payload_sha256.strip() or not receipt.response_payload_sha256.strip():
            raise PrematureLockReleaseViolation(
                "Idempotency receipt is missing key, request digest, or verified response digest."
            )

        release_token = (
            f"{receipt.resource_lock_id}|{receipt.fencing_token}|"
            f"{receipt.idempotency_key}|{receipt.response_payload_sha256}"
        )
        return hashlib.sha256(release_token.encode("utf-8")).hexdigest()