# Protobuf Style Guide

This guide defines protobuf conventions for MXAccess Gateway public gRPC and
gateway-to-worker IPC contracts.

## Baseline

- Use `proto3`.
- Keep public gateway contracts and worker IPC contracts in separate `.proto`
  files.
- Treat field numbers as permanent once released.
- Do not reuse removed field numbers or enum values. Reserve them.
- Keep generated code reproducible from checked-in `.proto` files.

## Source Documentation

- Maintain the existing documentation style in the `.proto` file and
  surrounding contract docs.
- Write comments that include business-specific or domain-specific context when
  that context is available from the contract, surrounding docs, or naming.
- Comment fields that carry MXAccess parity details, credential-sensitive data,
  raw HRESULT/status information, or compatibility constraints.
- Avoid comments that restate field types or message nesting.

## Naming

- Use `snake_case` for package names, file names, field names, and enum values.
- Use `PascalCase` for message, enum, and service names.
- Prefix enum values with the enum name or a clear abbreviation to avoid name
  collisions in generated languages.
- Keep MXAccess event family and command names recognizable in enum values.

## Compatibility

- Add fields instead of changing field meaning.
- Use `oneof` for command payloads, reply payloads, value unions, and event
  bodies.
- Add explicit `UNKNOWN` or `UNSPECIFIED` enum zero values.
- Preserve raw HRESULT, MXAccess status, and diagnostic metadata in replies and
  events.
- Use protocol version fields in worker IPC envelopes.

## Field Rules

- Do not use required semantics in application code for newly added optional
  fields unless compatibility behavior is documented.
- Prefer explicit wrapper messages for repeated structured values.
- Use signed or unsigned integer types based on the actual semantic range.
- Represent timestamps with `google.protobuf.Timestamp` unless the source value
  is not a real timestamp.
- Represent durations with `google.protobuf.Duration`.

## Security

- Do not define fields that require clients or workers to log secrets.
- Mark credential-bearing request fields clearly in comments.
- Keep raw values out of diagnostics unless an explicit redacted or opt-in path
  exists.

## Generated Code

- Do not hand-edit generated code.
- Keep generation commands documented near the contracts project.
- Regenerate all affected language outputs when a contract changes.