4. Layer 1: Transport

4.1 Wire Format

Frames are length-prefixed JSON over TCP. Each frame consists of:

+-------------------+---------------------------+
| 4 bytes           | N bytes                   |
| UInt32BE (length) | UTF-8 JSON payload        |
+-------------------+---------------------------+

• —The length field is a 4-byte big-endian unsigned 32-bit integer encoding the byte length of the JSON payload.
• —Implementations MUST reject frames with length 0 or length exceeding 1,048,576 bytes (1 MiB). Rejection MUST close the transport connection.
• —The JSON payload MUST be a valid JSON object with a type field (string). Frames that fail JSON parsing or lack a type field MUST be silently discarded.
• —Implementations MUST handle partial reads (TCP stream reassembly).
• —Implementations MUST silently ignore frames with unrecognised type values (forward compatibility).

4.2 Wire Examples

Handshake frame:

Length prefix: 00 00 00 57 (87 bytes)
Payload:
{
  "type": "handshake",
  "nodeId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "my-agent",
  "version": "0.2.0",
  "extensions": []
}

Ping frame:

Length prefix: 00 00 00 11 (17 bytes)
Payload: {"type":"ping"}

Memory-share frame (with CMB):

{
  "type": "memory-share",
  "timestamp": 1711540800000,
  "cmb": {
    "key": "h-b2c3d4e5f6a7b8c9",
    "createdBy": "melomove",
    "createdAt": 1711540800000,
    "fields": {
      "focus":       { "text": "user coding for 3 hours, energy declining" },
      "issue":       { "text": "sedentary since morning, skipping lunch" },
      "intent":      { "text": "recommend movement break before fatigue worsens" },
      "motivation":  { "text": "3 agents reported declining energy in last hour" },
      "commitment":  { "text": "fitness monitoring active, 10min stretch queued" },
      "perspective": { "text": "fitness agent, afternoon session, home office" },
      "mood":        { "text": "concerned, low energy", "valence": -0.3, "arousal": -0.4 }
    },
    "lineage": {
      "parents": ["h-a1b2c3d4e5f6"],
      "ancestors": ["h-a1b2c3d4e5f6"],
      "method": "SVAF-v2"
    }
  }
}

4.3 TCP Transport (LAN)

The primary transport. Nodes MUST listen on a TCP port and advertise it via DNS-SD (Section 5.1). Connection timeout MUST be no longer than 10,000 ms.

4.4 WebSocket Relay Transport (Internet)

For nodes not on the same LAN, a relay node forwards frames. Relay frames are JSON envelopes over WebSocket: { "to": "<nodeId>", "payload": <frame> }. The relay MUST NOT inspect or modify the payload. The relay is a peer, not a server — any always-on node MAY serve as a relay.

4.5 IPC Transport (Local)

Virtual nodes connect to their physical node via local IPC (Unix domain socket, named pipe, or localhost TCP). The framing is identical to TCP transport.