atelier-proto

Single source of truth for all gRPC service definitions and protobuf message types in the Atelier platform. This is both a language-agnostic proto repository (linted by buf) and a Rust library crate that exports the generated types via prost / tonic.

Follows the Atelier Engine Taxonomy v0.3.2 naming and structural conventions.

Repository Structure

atelier-proto/
├── Cargo.toml                            # Rust library crate with feature flags
├── build.rs                              # tonic_build driven by cargo features
├── src/lib.rs                            # re-exports all generated modules
├── buf.yaml                              # lint rules + breaking change detection (WIRE)
├── buf.gen.yaml                          # code generation targets (optional, for non-Rust)
├── atelier/
│   ├── identity/v1/
│   │   └── identity.proto                # shared ID newtypes, SequenceMetadata, AgentCapability
│   ├── command/v1/
│   │   └── command_channel.proto         # CommandChannelService (bidi stream, embeds Manifests)
│   ├── manifest/v1/
│   │   └── manifest_channel.proto        # Manifest message types (no service, rides on CommandChannel)
│   ├── telemetry/v1/
│   │   └── telemetry_channel.proto       # TelemetryChannelService (client-streaming upstream)
│   ├── data/v1/
│   │   ├── data_channel.proto            # DataChannelService (client-streaming upstream)
│   │   └── data_service.proto            # DataService (unary GetRawTrades, migrated from atelier-backend)
│   └── artifact/v1/
│       └── artifact_channel.proto        # ArtifactChannelService (client-streaming)
├── tests/                                # validation crate (depends on this lib with "full" features)
│   ├── Cargo.toml
│   └── src/lib.rs
└── README.md

Channel Map (Taxonomy v0.3.2)

Channel	Plane	Direction	Transport	Reliability	Proto Service
CommandChannel	Control	Bidirectional	gRPC bidi stream	At-least-once with ack	CommandChannelService
ManifestChannel	Control	Downstream	Embedded in CommandChannel	Exactly-once (idempotency key)	None (message-only)
TelemetryChannel	Data	Upstream	gRPC client-streaming	Best-effort + sequence numbers	TelemetryChannelService
DataChannel	Data	Upstream	gRPC client-streaming	At-least-once + gap detection	DataChannelService
ArtifactChannel	Data	Varies by Sink	gRPC client-streaming	At-least-once	ArtifactChannelService

Rust Crate Usage

Feature flags control which tonic stubs are generated:

# Server side (atelier-gateway, atelier-overseer) — generates *_server traits
atelier-proto = { path = "../atelier-proto", features = ["server"] }

# Client side (atelier-sdk) — generates *_client stubs
atelier-proto = { path = "../atelier-proto", features = ["client"] }

# No features — message types only (prost structs, no tonic services)
atelier-proto = { path = "../atelier-proto" }

use atelier_proto::atelier::identity::v1::SessionId;
use atelier_proto::atelier::data::v1::data_service_server::DataService;  // requires "server" feature
use atelier_proto::atelier::command::v1::command_channel_service_client::CommandChannelServiceClient;  // requires "client" feature

No build.rs or protoc needed in consuming crates — proto compilation happens once here.

Validation

The tests/ crate depends on this library with features = ["full"] and runs compile-time + runtime checks:

cd tests && cargo test

Combined with buf lint, this gives two validation layers: proto-level (syntax, naming, imports) and Rust-level (generated code compiles, types are accessible, feature flags work).

Linting and Breaking Change Detection

Requires buf:

buf lint
buf breaking --against '.git#branch=main'

Versioning

Tagged with semver (v0.0.10, v0.1.0, ...). Consumers reference via path dependency.