# Worker Frame Protocol

The gateway uses the worker frame protocol to move `WorkerEnvelope` protobuf
messages over a bidirectional named pipe. The frame layer is deliberately small:
it handles message boundaries, size limits, protobuf parsing, and envelope
validation before higher-level worker client code routes commands, replies,
events, and faults.

## Frame Format

Each frame starts with a four-byte little-endian unsigned payload length,
followed by the serialized `WorkerEnvelope` payload:

```text
uint32 little-endian payload_length
payload_length bytes protobuf WorkerEnvelope
```

The reader rejects zero-length payloads and payloads larger than the configured
maximum before allocating the payload buffer. The default maximum is 16 MiB,
matching the gateway process design.

## Envelope Validation

`WorkerFrameReader` and `WorkerFrameWriter` validate each envelope against the
owning session before returning or writing it:

- `protocol_version` must match the configured worker protocol version,
- `session_id` must match the owning gateway session,
- the envelope must contain one typed `body` value.

Protocol violations throw `WorkerFrameProtocolException` with a
`WorkerFrameProtocolErrorCode` so callers can distinguish malformed frames,
oversized frames, protocol version mismatches, and session mismatches.

## Verification

Run the focused tests after changing the frame protocol:

```bash
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerFrameProtocolTests
```

Run the gateway build because the frame protocol is part of
`MxGateway.Server`:

```bash
dotnet build src/MxGateway.Server/MxGateway.Server.csproj
```

## Related Documentation

- [Gateway Process Detailed Design](./GatewayProcessDesign.md)
- [Protobuf Contracts](./Contracts.md)