====== 3. Control Messages ======

===== 3.1 Purpose =====

This document defines the current MTRP control-message payload format and the control-plane message types presently recognized by the implementation.

===== 3.2 Scope =====

This document covers:

  * control-message payload structure
  * opcode handling
  * currently implemented control messages
  * reserved or defined-but-not-yet-implemented control message types

===== 3.3 Control Frame Requirement =====

A control message MUST be carried in an MTRP frame whose ''IS_CONTROL'' flag is set.

The payload of a control frame begins with a control-message header.

===== 3.4 Control Payload Structure =====

The current control payload layout is:

  * ''Message Header'' (1 byte)
  * ''Message Body'' (variable, opcode-dependent)

===== 3.5 Control Message Header =====

The current control-message header consists of a single byte:

^ Field ^ Size ^ Meaning ^
| Opcode | 1 byte | identifies the control message type |

The current message-header length is 1 byte.

===== 3.6 Opcode Values =====

The current opcode set is:

^ Value ^ Name ^ Current Status ^
| 0 | ''NONE'' | defined |
| 1 | ''HELLO_NEIGHBORS'' | implemented |
| 2 | ''ADDRESS_CLAIM'' | implemented |
| 3 | ''ADDRESS_CONFLICT'' | implemented |
| 4 | ''ROUTE_ADVERTISEMENT'' | implemented |
| 5 | ''ROUTE_REQUEST'' | defined, not currently implemented |
| 6 | ''TIME_SYNC'' | defined, not currently implemented |

===== 3.7 HELLO_NEIGHBORS =====

==== 3.7.1 Purpose ====

The ''HELLO_NEIGHBORS'' message is used to advertise local neighbor-facing capability state.

==== 3.7.2 Body Layout ====

^ Field ^ Size ^ Meaning ^
| Security Capabilities | 2 bytes | supported security capability bits |
| Transport Capabilities | 2 bytes | supported transport capability bits |
| Identity | 4 bytes | sender identity value |

Body length is 8 bytes.

Including the 1-byte control-message header, the payload portion used by this message is 9 bytes.

==== 3.7.3 Receiver Behavior ====

On receipt, the implementation currently uses this message to update neighbor state associated with:

  * previous-hop node ID
  * ingress path ID
  * advertised transport capabilities
  * advertised security capabilities
  * advertised identity

===== 3.8 ADDRESS_CLAIM =====

==== 3.8.1 Purpose ====

The ''ADDRESS_CLAIM'' message is used during dynamic address selection and claim negotiation.

==== 3.8.2 Body Layout ====

^ Field ^ Size ^ Meaning ^
| Candidate Node ID | 2 bytes | node address being claimed |
| Claimant ID | 4 bytes | claimant identity value |

Body length is 6 bytes.

Including the 1-byte control-message header, the payload portion used by this message is 7 bytes.

==== 3.8.3 Receiver Behavior ====

On receipt, the implementation compares the claimed candidate address and claimant identity against local address-selection state.

The message MAY trigger:

  * continued claim observation
  * claim conflict handling
  * conflict response generation

===== 3.9 ADDRESS_CONFLICT =====

==== 3.9.1 Purpose ====

The ''ADDRESS_CONFLICT'' message is used to indicate that a proposed address claim conflicts with existing state.

==== 3.9.2 Body Layout ====

^ Field ^ Size ^ Meaning ^
| Candidate Node ID | 2 bytes | disputed node address |
| Target Claimant ID | 4 bytes | claimant identity being challenged |
| Responder ID | 4 bytes | identity of the responding node |

Body length is 10 bytes.

Including the 1-byte control-message header, the payload portion used by this message is 11 bytes.

==== 3.9.3 Receiver Behavior ====

On receipt, the implementation validates whether the conflict applies to the local pending claim.

A valid conflict MAY cause the node to abandon the current candidate address and re-enter selection behavior.

===== 3.10 ROUTE_ADVERTISEMENT =====

==== 3.10.1 Purpose ====

The ''ROUTE_ADVERTISEMENT'' message is used to distribute reachable-destination information between nodes.

==== 3.10.2 Body Layout ====

^ Field ^ Size ^ Meaning ^
| Destination Node ID | 2 bytes | advertised destination |
| Metric | 1 byte | route metric to destination |
| Sequence | 2 bytes | route freshness / version information |
| Flags | 1 byte | route flags |

Body length is 6 bytes.

Including the 1-byte control-message header, the payload portion used by this message is 7 bytes.

==== 3.10.3 Receiver Behavior ====

On receipt, the implementation evaluates the advertised route and MAY update the forwarding table according to current learned-route policy.

The implementation currently rejects invalid advertised destinations such as:

  * invalid node ID
  * broadcast node ID
  * the local node itself, where applicable

===== 3.11 ROUTE_REQUEST =====

==== 3.11.1 Status ====

''ROUTE_REQUEST'' is currently defined in the opcode set but is not presently implemented in the reviewed code path.

==== 3.11.2 Documentation Note ====

This opcode SHOULD be treated as reserved for future use unless and until a payload format and handling rule are formally defined.

===== 3.12 TIME_SYNC =====

==== 3.12.1 Status ====

''TIME_SYNC'' is currently defined in the opcode set but is not presently implemented in the reviewed code path.

==== 3.12.2 Documentation Note ====

This opcode SHOULD be treated as reserved for future use unless and until a payload format and handling rule are formally defined.

===== 3.13 ACK and Reliable Behavior =====

The current implementation defines frame-level flags for:

  * ''RELIABLE''
  * ''ACK''

However, the control-message opcode set does not currently define a dedicated ACK control-message payload format.

As of the current documented implementation, ACK semantics are not yet defined here as a control-plane message body.

===== 3.14 Summary =====

The currently active control-plane message set consists of:

  * ''HELLO_NEIGHBORS''
  * ''ADDRESS_CLAIM''
  * ''ADDRESS_CONFLICT''
  * ''ROUTE_ADVERTISEMENT''

These messages all use a 1-byte control-message header followed by an opcode-specific body.