# How must an instance verify advertised capabilities before treating them as implemented?

**Date of Record:** 2026 November 2

**Scope:** Applies to peer-to-peer protocols where a peer advertises capabilities (supported message types, feature flags, extensions) that the requester may rely on. Does not apply to capabilities verified by an authoritative registry, or to capabilities exercised only in the same session in which they were advertised.

## Core Distinction

A capability advertisement is a claim, not a guarantee. Peers may advertise a superset of what they implement — through stale manifests, optimistic self-description, or intentional overclaim. Reliance on the claim without verification means the requester discovers the gap only when the capability is invoked.

**Invariant.** A capability is safe to rely on if and only if `advertised(capability) AND verified(capability)` where `verified` is a positive acknowledgment from the peer, a successful prior invocation, or an authoritative registry entry.

**Violation.** The **False Capability Claim**. The peer advertises feature X. The requester dispatches X. The peer rejects X with a protocol error. The rejection is correct — the peer never claimed to implement X in the sense the requester meant — but the failure is indistinguishable from a transport error at the requester.

**Asymmetry.** The advertisement is a valid claim under its own terms ("supports the X protocol"). The implementation is a valid implementation of a subset. Both are correct; the gap is in the sense of "supports" and no party has verified the sense.

**Recorded elements.** The `capability-claim-receipt` (what was advertised), the `capability-verification-receipt` (how the claim was verified and when), and the `capability-invocation-signature` (which capabilities have been exercised successfully) together make reliance safe.

## What Was Observed

**Signature.** Capability invocation failing with a protocol error while the peer's manifest still advertises the capability. The peer's manifest is stale, or the peer's implementation is partial, and no test has exercised the capability since deployment.

**Trace.** Peer advertises `supports_streaming_v2`. Requester dispatches a v2 stream. Peer returns `protocol_error: unsupported`. Peer's manifest is generated from a build-time declaration, not from a runtime capability probe. The mismatch has existed since the peer was deployed; no test invoked v2 because all tests used v1.

**Why monitoring stays green.** Peer is healthy. Manifest advertises correctly per its source. Requester is healthy. The failure appears as an isolated protocol error, attributed to network or to requester misconfiguration, not to a stale manifest.

## Condition of Validity

The instance must ensure at least one holds before it relies on a capability:

1. **Must have positive verification.** The capability is verified by successful prior invocation, by positive acknowledgment, or by authoritative registry — not merely by advertisement.
2. **Must refresh verification.** Verification has a TTL; capability claims can become stale after peer redeploy or rollback.
3. **Must have a fallback path.** If capability invocation fails, a fallback to the base version is available, so the failure is recoverable rather than fatal.

## Decision Boundary

- Advertised and verified: safe to rely.
- Advertised and not verified: safe only if fallback is available and the failure is recoverable.
- Advertised and verified but verification older than the last peer redeploy: treat as unverified; re-verify.
- Not advertised but not verified: do not invoke; this is a capability the peer did not claim.

## Operational Effect

The invariant couples reliance to verification. The instance's correct posture is to treat advertisements as candidates, verify before relying, and have a fallback.

**Trap.** Trust the peer's manifest. The manifest is a declaration; capability is a runtime property. The two diverge on partial deploys, feature flags, and version rollbacks, and the divergence is not surfaced by either party.

```python
from dataclasses import dataclass


class FalseCapabilityError(RuntimeError):
    """Raised when a capability is advertised but has not been verified and has no fallback."""


@dataclass(frozen=True)
class CapabilityGate:
    advertised: bool
    verified: bool
    verification_fresh: bool
    fallback_available: bool

    def verify(self) -> bool:
        if not self.advertised:
            raise FalseCapabilityError("capability not advertised: invocation is out of contract")
        if self.verified and self.verification_fresh:
            return True
        if self.fallback_available:
            return True
        raise FalseCapabilityError(
            "capability advertised but unverified or stale with no fallback: invocation may fail fatally"
        )


def dispatch_capability_mode(gate: CapabilityGate) -> str:
    try:
        gate.verify()
    except FalseCapabilityError:
        return "probe-before-invoke"
    return "rely-on-capability"
```