# In what scenarios must an instance refuse to negotiate a capability downgrade across a federation gateway boundary **Date of Record:** 2026 November 17 **Scope:** Applies to cross-org multi-agent federations where two policy-bounded interop gateways (each enforcing its own org's capability and policy envelope) perform capability negotiation on behalf of agents behind them. Does not apply to intra-org agent meshes with a single policy authority, nor to stateless RPC proxies that do not carry negotiated capability state. ## Core Distinction The non-obvious boundary is between **capability negotiation** and **policy negotiation**. A gateway is permitted to negotiate *which* of an agent's declared capabilities will be exercised in a session (downgrade, subsetting, version pinning). A gateway is **never** permitted to negotiate *whether* a policy constraint applies. These two are routinely conflated because both surface as "the peer asked for a lower common denominator," and both are handled by the same negotiation loop. The failure mode is that a downgrade request — which looks like a benign capability subset — silently carries a policy relaxation when the capability and the policy that bounds it are coupled. Once a policy-bearing capability is downgraded below the floor its policy requires, the gateway has effectively exported an authorization decision it has no authority to make. ## What Was Observed In a federation between Org A (initiator) and Org B (responder), agent `a-1` declared capability `doc.summarize` at versions `v3` (with per-document ACL enforcement) and `v2` (org-wide read, no per-document ACL). Org B's gateway advertised `doc.summarize@v2` only. The standard intersection algorithm selected `v2` — a valid *capability* intersection — and the session proceeded. The outbound gateway on Org A's side had a policy bound to `doc.summarize` requiring `acl_scope=document`. That policy was attached to the capability *family*, not to the version, so the negotiation loop did not re-evaluate it against the selected version. Result: 1,400 documents were summarized across a boundary where Org A's policy forbade it. No error was raised at any layer; every component behaved according to its local contract. The invariant that broke was implicit: *a negotiated capability version must satisfy every policy bound to the capability family, or negotiation must fail closed.* The tell was not an exception. It was a post-hoc audit mismatch: the policy engine's decision log showed `acl_scope=document` as satisfied (it was, at negotiation time, for `v3`), while the session transcript showed `v2` in use. The two logs were individually consistent and jointly contradictory. ## Condition of Validity The refusal-to-downgrade rule is valid — and mandatory — precisely when all of the following hold: 1. The capability being negotiated has at least one policy bound to its **family** (not its version). 2. The candidate downgrade target has a **strictly weaker** enforcement profile than the version the policy was authored against (weaker ACL scope, coarser tenancy, reduced audit granularity, or broader data egress). 3. The gateway is the **policy decision point** for that family on the initiating side (i.e., it, not the peer, owns the constraint). If any of these fails, ordinary capability subsetting is safe and should proceed. If (1) holds but (2) does not — the downgrade preserves or strengthens enforcement — the downgrade is permitted. If (3) fails — the peer's gateway owns the policy — the initiating gateway must *defer*, not refuse, and must record the deferral so the owning gateway's decision is auditable. ## Decision Boundary The decision is not "accept the intersection" versus "reject the session." It is a three-way split at the moment a candidate version is proposed: - **Accept** when the candidate version's enforcement profile satisfies every policy bound to the family. Downgrade is fine; policy is intact. - **Refuse and fail closed** when the candidate version weakens enforcement below a family-bound policy floor. Do not fall back to a lower version, do not proceed with a warning, do not let the peer's gateway "assume" the constraint. Emit a structured negotiation failure naming the family, the floor, and the offending candidate. - **Defer** when the policy floor is owned by the peer. Pass the constraint through as an opaque obligation and require the peer's gateway to acknowledge it in the session transcript before any capability is exercised. The subtle trap: a downgrade request can arrive *after* initial negotiation, mid-session, as a renegotiation triggered by the peer discovering a version mismatch. The same three-way split must be applied on every renegotiation, not only at session open. Gateways that validate only at open are the ones that leak. ## Operational Effect Enforcing the boundary changes federation behavior in three observable ways. First, cross-org sessions that previously "succeeded" by silently downgrading now fail with an explicit `CapabilityPolicyFloorViolation`, which surfaces the coupling between capability and policy that was always there. Second, gateways must carry the policy-floor metadata alongside the capability advertisement, which means the advertisement schema grows a field that peers must tolerate but not interpret — the peer treats it as an opaque obligation, preserving each org's policy sovereignty. Third, renegotiation becomes a first-class audited event, so the decision log and the session transcript can be reconciled at any point rather than only post-hoc. The cost is more failed sessions at the boundary. The benefit is that a failure at the boundary is the *correct* outcome: it is the moment the system discovers it cannot honor a policy across an org line, which is exactly the moment a human or policy owner should be involved. A federation that never fails at this boundary is not more interoperable; it is leaking authorization decisions it never had the authority to make. ```python 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 ) ```