Skip to main content

Versioning and compatibility

Independent version axes​

Software release, contract module release, wire protocol version, event schema version, inventory schema version, and agent configuration format are distinct. The current agent declares wire protocol 1 and event/inventory schema 1; that does not make the application a "version 1" product.

The agent pins a published contract release and interprets backend refusals against the values it intentionally sent. A rejected schema or declared enum can signal incompatibility; an unset required value or unknown enum constructed by a bug is not automatically an incompatible server.

Additive contract changes​

The contracts policy adds fields rather than renumbering, renaming, or removing them. Buf checks compatibility against the branch baseline. Incompatible shape changes use a new vN package so independently deployed consumers can migrate deliberately.

make lint
make generate
make check
make breaking
make verify

Run in Seagull-contracts. make verify covers lint, module verification, generation consistency, and build; make breaking is a separate compatibility gate. Commit regenerated Go bindings alongside schema changes.

Behavioral compatibility​

Unknown protobuf fields may be ignored, but that does not permit a silent change to what a response means. A new interpretation that an older client cannot safely make requires an explicit protocol transition. The agent's recorded backend exchanges limit compatibility claims to the platforms they were recorded from; they do not establish compatibility with every version bearing a similar schema.

Capability negotiation​

The backend descriptor and version declarations exist. The agent currently has version constants and refusal classification, not a live descriptor negotiation loop. Future collectors and control features must negotiate only capabilities actually supported by both sides. Do not create a competing agent-local envelope or handshake schema.

Source evidence​

Reviewed against the source baseline. Seagull-contracts/Makefile · Seagull-contracts/buf.yaml · Seagull-agent-v2/internal/protocol/protocol.go · Seagull-agent-v2/tests/compatibility/gateway_test.go.