Shared contracts
Seagull-contracts owns messages exchanged among independently released platform components. The agent does not import backend implementation to learn a protocol; both consume a published contract release.
Contract families
| Family | Meaning |
|---|---|
| Event | Typed security observation |
| Ingest | Event batch, durable ACK, and refusal |
| Platform | Descriptor and version/capability declarations |
| Detection | Evidence-bearing analytical result |
| Hunt | Bounded query and result pages |
| Control | Sessions, permissions, and caller grants |
| Ruleset | Typed rules, versions, publication, activation |
| Alert | Operator work and occurrence evidence |
| Incident | Correlation story with operational lifecycle |
| Agent | Registry, admission, and certificate lifecycle |
| Inventory | Asset scans and typed items |
| Vulnerability | Advisory intelligence and feed provenance |
Generation and ownership
Canonical .proto definitions live under proto/seagull/.../v1. Generated Go bindings are committed so consumers need no generator to build. CI regenerates and fails on differences. Documentation extracts references from a pinned source snapshot; it does not own a second protocol definition.
Both backend and agent currently pin v0.14.0. The introductory contracts README's old go get ...@v0.1.0 example is not the current integration baseline. Use each consumer's go.mod and recorded compatibility.
Boundaries of a schema
A declared inventory message does not prove an endpoint collector exists. A platform descriptor does not imply the agent currently fetches it. Wire structure, handler support, runtime composition, and release compatibility must be evaluated together.
Source evidence
Reviewed against the source baseline. Seagull-contracts/README.md · Seagull-contracts/Makefile · Seagull-backend-v2/go.mod · Seagull-agent-v2/go.mod.