Skip to content

Version Negotiation or Capability Probe

Handshake protocol — instantiates Asymmetric Interface Tolerance Calibration

Has the two sides advertise and agree on a shared version or capability set before exchanging real data, so each tailors what it sends and expects to what the other actually supports.

Tolerance is expensive when it means guessing what the other party can handle on every message. Version Negotiation or Capability Probe replaces the guessing with a handshake: before real data flows, each side advertises what versions and features it supports, and they settle on a shared subset to use. Its defining move is to establish mutual knowledge of the other end up front — who is speaking, at what version, with which capabilities — so both sides can then be precise instead of defensively tolerant. Where the rest of the archetype tunes how forgiving to be about unknown inputs, this mechanism reduces how many unknowns there are in the first place, making compatibility an explicit, recorded agreement rather than an inference.

Example

You plug a laptop into an unfamiliar office printer. Before sending a document, the driver queries the printer's capabilities — over IPP the printer returns the attributes it supports: which page languages (PostScript, PCL), duplex, color, paper sizes, resolutions. The laptop intersects that list with its own and picks a shared best option — say, duplex color PostScript at 600 dpi — and prints in exactly that. Neither side had to tolerate a mystery: the printer didn't receive a job in a language it can't render, and the laptop didn't send blind and hope. The negotiated result — "this session speaks PostScript, duplex, 600 dpi" — is recorded for the job and governs everything sent, so the interface is precise because the two ends compared notes first.

How it works

  • Advertise, don't assume. Each side publishes its supported versions and features (a capability descriptor or a version header) rather than presuming what the other implements.
  • Map who's on the other end. The exchange establishes each party's role and level — client vs server, this version, these optional features — turning an anonymous peer into a known counterpart.
  • Select a common subset. The two capability sets are intersected and a shared operating point is chosen, typically the most capable option both support.
  • Record and pin the agreement. The negotiated version/capability set is written down for the session or connection, so every later message is interpreted in that agreed context instead of re-guessed.

Tuning parameters

  • Negotiation granularity — a single version number vs a fine-grained per-feature capability list. Feature-level is precise but chatty; a version number is simple but coarse.
  • Selection rule — how the shared operating point is chosen (highest common version, most capable mutual set, or a safe default). Encodes whether the interface optimizes for capability or caution.
  • Floor enforcement — whether a minimum acceptable version is required, so negotiation can't be pushed down to an unsafe or deprecated option.
  • Handshake cost — whether negotiation happens per-connection, per-session, or is cached across sessions, trading round-trip latency against staleness of the recorded agreement.
  • Fallback behavior — what happens when no common version exists — hard failure, a defined baseline, or an adapter — so "incompatible" has a defined outcome rather than a hang.

When it helps, and when it misleads

Its strength is that it shrinks the tolerance problem at the root: with an agreed version and capability set pinned for the exchange, both sides can be strict and precise, and the interface can evolve because new capabilities are discovered and negotiated rather than assumed and hoped for. It gives forward and backward compatibility a clean handle — old and new can meet in the middle knowingly.

It misleads mainly through the negotiation itself becoming an attack or failure surface. A middleman that tampers with the advertised capabilities can force both ends down to the weakest mutually-supported option — a downgrade attack[1] — which is why a version floor matters. Negotiation also adds a round trip and a combinatorial testing burden: every supported version pair is a configuration that can harbor its own bugs, and a rarely-exercised fallback path is where they hide. Its classic misuse is treating the handshake as decoration — negotiating a version and then not honoring it, so the recorded agreement and the real behavior drift apart. The discipline is to enforce a floor, honor the negotiated context literally, and test the fallback paths as first-class, not afterthoughts.

How it implements the components

  • interface_role_map — the handshake establishes who each party is and what it supports, mapping the roles and levels at the two ends of the interface.
  • compatibility_context_record — the negotiated version/capability set is recorded for the session, becoming the shared context every later message is interpreted against.

It establishes shared context but does not set how strict each side is within it (that's Tolerant Reader / Strict Writer Policy or Strict Bidirectional Contract Gate), does not hold the static grid of which versions interoperate (Compatibility Matrix), and does not translate between mismatched versions when no common one exists (Adapter or Translation Shim).

References

[1] Downgrade attack — when an adversary interferes with a capability or version negotiation to force both parties onto a weaker, more exploitable option they both still support. It is the standard security failure mode of any negotiated handshake, and the reason a negotiated interface usually enforces a minimum acceptable version. ↩