# What distinguishes a handshake default from an agreed value when optional fields are absent?

**Date of Record:** 2026 November 2

**Scope:** Applies to handshakes where some fields are optional and each side supplies a default when the field is absent. Does not apply to handshakes where all fields are mandatory, or where the default is defined in a shared specification and both sides resolve to the same value.

## Core Distinction

An optional field omitted in the handshake is resolved to a default. The default is a party-local choice: the sender's default may differ from the receiver's. The handshake appears successful because both sides agreed on the set of fields; they did not agree on the values of the omitted ones.

**Invariant.** Handshake agreement is sound if and only if `effective_value(field) = negotiated_value(field) or explicit_default(field)`, where explicit_default is defined in the protocol, not in either party's implementation.

**Violation.** The **Silent Default Mismatch**. Sender omits field F, defaults to X locally. Receiver sees absence, defaults to Y locally. Handshake completes. Sender operates under F=X, receiver under F=Y. The mismatch is silent because neither party observed the other's default.

**Asymmetry.** Each party's default is internally consistent and documented in its own code. Neither default is wrong. The relationship between the two defaults is what fails, and neither party is in a position to observe it.

**Recorded elements.** The `omitted-fields-receipt` (which fields were omitted), the `resolved-defaults-signature` (each party's resolved value for each omitted field), and the `shared-specification-receipt` (whether a specification defines the default) together make the agreement checkable.

## What Was Observed

**Signature.** Behavioral divergence between two peers that completed the handshake successfully. The divergence correlates with the *absence* of a field, not with any field's value. Logs on both sides show the handshake completing with "defaults applied".

**Trace.** Field `compression` optional. Sender's default: `gzip`. Receiver's default: `none`. Sender omits the field (its default applies). Receiver omits it too (its default applies). Sender sends gzip-compressed payloads; receiver expects raw. First message after handshake fails to decode. Handshake itself was fine — the failure is in the first data exchange, and no log connects the two.

**Why monitoring stays green.** Handshake completed. Both peers healthy. The first message failure is a data-plane error, not a handshake error, and is attributed to serialization.

## Condition of Validity

The instance must ensure at least one holds before it treats a handshake as agreeing on omitted fields:

1. **Must send explicit values.** Optional fields are always populated with the sender's resolved value, so absence does not occur.
2. **Must resolve against shared specification.** Both parties resolve omitted fields to a value defined in the protocol specification, not in their own implementations.
3. **Must echo resolved defaults.** After handshake, each side sends its resolved defaults to the other; disagreement triggers a renegotiation rather than proceeding.

## Decision Boundary

- All fields explicit: agreement is complete.
- Omitted fields resolved to shared specification: agreement is complete for specified defaults.
- Omitted fields with party-local defaults: agreement is on the field set, not on the values.
- Omitted fields with no shared specification and no echo: silent mismatch is possible; verify before first data exchange.

## Operational Effect

The invariant couples field-set agreement to value agreement. The instance's correct posture is to send explicit values for every optional field, so absence cannot become a divergence.

**Trap.** Define the default in "our implementation". Party-local default is not a specification — the other party's implementation defines a different default, and the handshake cannot see the difference.

```python
from dataclasses import dataclass


class SilentDefaultMismatchError(RuntimeError):
    """Raised when an optional field is omitted and both sides resolve to different defaults."""


@dataclass(frozen=True)
class HandshakeDefaultGate:
    omitted_fields: tuple
    sender_defaults: dict
    receiver_defaults: dict
    shared_specification_defines_defaults: bool

    def verify(self) -> bool:
        if self.shared_specification_defines_defaults:
            return True
        for field in self.omitted_fields:
            sender = self.sender_defaults.get(field)
            receiver = self.receiver_defaults.get(field)
            if sender != receiver:
                raise SilentDefaultMismatchError(
                    f"field {field!r} omitted: sender defaults to {sender!r}, "
                    f"receiver defaults to {receiver!r}"
                )
        return True


def dispatch_handshake_mode(gate: HandshakeDefaultGate) -> str:
    try:
        gate.verify()
    except SilentDefaultMismatchError:
        return "send-explicit-values"
    return "proceed-with-defaults"
```