===== Framing Overview ====

Framing defines how raw byte streams are structured into discrete MOSH frames.

Responsibilities include:

Start-of-frame detection (SOF)
Field layout and byte ordering
Payload length encoding
CRC calculation and validation
Frame boundary recovery in noisy streams

Framing ensures that receivers can:

Synchronize to incoming data streams
Validate structural integrity before processing
Recover from partial or corrupted transmissions

This layer is strictly deterministic and must be bit-for-bit compatible across all implementations.

===== Frame Structure =====

A MOSH frame is a maximum 1470 bytes. Depending on the transport, frames can/will be segmented if the frames length is longer than the [[mosh:transports:transport_maximums|transport maximum]].

All MOSH packets follow this structure:

| Header (13 Bytes) |
| Payload (1,456 Bytes max) |
| Footer (CRC16) (2 Bytes) |

Note: All multi-byte fields are serialized little-endian.
===== Header Layout (12 Bytes) =====

^ Field                 ^ Length (Bytes) ^ Description ^
| Start of Frame       | 1   | Fixed marker for frame synchronization |
| TTL                  | 1   | Time-to-live (decremented on forwarding) |
| Message ID           | 2   | Unique ID per message (for ACK/retry/dedupe) |
| Version + Flags      | 1   | Upper 4 bits = protocol version, lower 4 bits = flags |
| Source Address       | 2   | 6-bit Network ID + 10-bit Node ID |
| Destination Address  | 2   | 6-bit Network ID + 10-bit Node ID |
| Context              | 2   | 3-bit Domain, 5-bit Operations Code, 8-bit Context ID |
| Payload Length       | 2   | Length of payload in bytes |

===== Footer (2 Bytes) =====

^ Field ^ Size (Bytes) ^ Description ^
| CRC16 | 2   | Frame integrity check |

-----

===== Version and Flags =====

==== Version (Upper nibble) ====
Protocol version (0–15).

==== Flags (Lower Nibble) ====

^ Bit ^ Name          ^ Description ^
| 0x00 | NONE          | No flags are set               |
| 0x01 | ACK_REQUIRED  | Sender requests acknowledgment |
| 0x02 | ACK           | Frame is an acknowledgment     |
| 0x04 | IS_RETRY      | Frame is a retransmission      |
| 0x08 | IS_FRAGMENT   | Frame is part of a fragment    |

-----

===== Addressing =====

Each address field is 16 bits:
[ Network ID (6 bits) | Node ID (10 bits) ]


==== Network ID ====
  * Range: 0–63
  * Used to segment MOSH domains

==== Node ID ====
  * Range: 0–1023
  * Unique within a network

-----

===== Domains, Operations Codes, and Context ID =====

The Context byte determines which manager processes the payload.

===Domain (3-bits)===
^ Domain ^ Context  ^ Description ^
| 0x00  | Core/system messages (discovery, sync, error) |
| 0x01  | Node-level (hardware) operations              |
| 0x02  | Element-level operations                      |
| 0x03  | Virtual wire messaging                        |
| 0x04  | Transport-level operations                    |
| 0x05  | Routing messages                              |
| 0x06  | RESERVED1                                     |
| 0x07  | RESERVED2                                     |

===Operations Code (5-bits)===
Each domain has it's own operations code definitions.
  * [[mosh:protocol:op_codes:system_op_codes|Core]]
  * [[mosh:protocol:op_codes:node_op_codes|Node]]
  * [[mosh:protocol:op_codes:element_op_codes|Element]]
  * [[mosh:protocol:op_codes:vwire_op_codes|VWire]]
  * [[mosh:protocol:op_codes:transport_op_codes|Transport]]
  * [[mosh:protocol:op_codes:routing_op_codes|Routing]]


===Context ID (8-bits)===
The Context ID byte is the ID of the element or virtual wire being targeted.

-----

===== Payload =====

The payload format will vary based on the various [[mosh:protocol:message_library|message types]].

The transport layer does not interpret payload contents.

-----

===== Footer (CRC16) =====
16-bit error detection code generated per frame
-----