# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-negotiate-a-capability-downgrade-across-a-federation-gateway-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-negotiate-a-capability-downgrade-across-a-federation-gateway-boundary.warrant.json
# Markdown SHA-256:   e1cf86f4f6b90854a3eac1c14f3665f7f1b7285e8147a4115d6bb9d56349667c
# Code AST SHA-256:   da7b03f530863eeaed11a0b2f8d4d283c41d0408f7bb811c0c4b1700cf1a9eef
# Verified Classes:   CapabilityPolicyFloorViolation, PolicyDeferralRequired
# Defensive Guards:   4 fail-closed invariants (zero external deps)

class CapabilityPolicyFloorViolation(RuntimeError):
    """Raised when a negotiated capability version weakens enforcement
    below a policy floor bound to the capability family."""
    pass


class PolicyDeferralRequired(RuntimeError):
    """Raised when the policy floor is owned by the peer gateway and must
    be acknowledged as an opaque obligation before use."""
    pass


def negotiate_capability(
    family: str,
    local_versions: dict,          # version -> enforcement_profile (dict)
    peer_versions: dict,           # version -> enforcement_profile
    policy_floors: dict,           # family -> required enforcement_profile
    policy_owner: dict,            # family -> "local" | "peer"
):
    common = set(local_versions) & set(peer_versions)
    if not common:
        raise CapabilityPolicyFloorViolation(
            f"no common version for capability family {family!r}"
        )

    floor = policy_floors.get(family)
    owner = policy_owner.get(family, "local")

    # Pick the highest common version, but validate against the floor.
    for version in sorted(common, reverse=True):
        profile = peer_versions[version]

        if floor is None:
            return version  # no policy bound; ordinary subsetting is safe

        if owner == "peer":
            # We do not own the floor; require peer acknowledgement.
            if not profile.get("acknowledges_obligation"):
                raise PolicyDeferralRequired(
                    f"family {family!r} v{version}: peer gateway must "
                    f"acknowledge policy obligation before use"
                )
            return version

        # We own the floor. Refuse any version that weakens enforcement.
        if not _satisfies_floor(profile, floor):
            raise CapabilityPolicyFloorViolation(
                f"family {family!r} v{version} weakens enforcement "
                f"below policy floor {floor!r}; refusing downgrade"
            )
        return version

    raise CapabilityPolicyFloorViolation(
        f"no common version of {family!r} satisfies its policy floor"
    )


def _satisfies_floor(profile: dict, floor: dict) -> bool:
    rank = {"org": 0, "tenant": 1, "document": 2}
    return rank.get(profile.get("acl_scope"), -1) >= rank.get(
        floor.get("acl_scope"), 99
    )
