orbit/proto

The Connect-RPC v1 contract between the agent, the admin server, and the admin UI. You never import it directly; agent and server pin it for you. It matters when you change the wire format.

The single source of truth is nucleus/admin/v1/admin.proto.

Generated outputs

Both targets are committed, so a fresh checkout compiles without buf installed:

• gen/go/nucleus/admin/v1/ — Go message structs and Connect-RPC service stubs, imported by orbit/agent and orbit/server.
• ../ui/src/fleet/gen/nucleus/admin/v1/ — TypeScript stubs consumed by the Connect-Web client in the UI.

Regenerating is a manual step: run make proto after any .proto change. Nothing verifies a clean diff automatically today, so it is on you to regenerate and commit.

Day-to-day commands

# Regenerate Go + TypeScript stubs (committed). Run after any .proto change.
make proto

# Lint with buf's STANDARD ruleset (plus documented exceptions for the shared
# Frame/Event/Snapshot types).
make proto-lint

# Verify nothing in this change is wire-incompatible vs main.
make proto-breaking

Evolution rules

The wire format is append-only. A rolling update means old agents talk to new servers and the reverse, so every change must stay backward- and forward-compatible. In practice:

• never remove fields;
• never reorder oneof tags;
• never reuse field numbers.

Before changing the proto, read EVOLUTION.md in the module for the full rules.

Version pins

buf.gen.yaml generates the fleet UI's TypeScript with bufbuild/es v2 alone: protobuf-es 2 emits the messages and the service descriptors from one generator, and connect-es 2 consumes them (createClient, create(Schema, …)), so the connectrpc/es generator of the first generation is gone. The generator version mirrors @bufbuild/protobuf in ui/package.json; the two move together, by hand, because a stub generated by one major and consumed by the other does not type-check.