Contract-definition mechanism: buf v2 + protoc-gen-go/grpc-go toolchain #110
Notifications
Due Date
No due date set.
Reference: sam/archie#110
Reference in new issue
Block a user
Groundwork for all service-decomposition contracts (resolved open
question #2 in docs/prds/service-decomposition.md). Every later phase
(starting with Phase 0's ChatContract seam) needs this toolchain in place
before it can define a wire contract.
Decision (already made, not open for redesign here): buf v2 driving
protoc-gen-go + protoc-gen-go-grpc, targeting grpc-go -- NOT connect-go,
because connect-go's net/http-based client breaks the service-discovery
research's gRPC resolver plumbing for K8s DNS and NATS-KV custom
resolvers. google.golang.org/grpc becomes a direct dependency (today only
google.golang.org/protobuf is an indirect one, go.mod:59).
Layout: one committed proto//v1/ tree (one buf module, not
per-service modules), directory name matching the canonical
service/registry/DNS/chart name. Generated Go is committed (not
build-time generated) to internal/contracts//v1/, produced via
buf's managed mode (go_package_prefix) + paths=source_relative, per
docs/architecture/dependencies-and-contracts.md:55's per-domain
wire-contract ownership rule.
Versioning: directory versioning (v1, v2, ...); a breaking change gets a
new vN directory, never an in-place edit. Enforced by
buf breaking --against '.git#branch=main,subdir=proto'.Full reasoning, scratch-verified buf/connect-go toolchain results, and
the CI shallow-checkout gotcha: see
docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2
Acceptance criteria
root; protoc-gen-go and protoc-gen-go-grpc wired as buf plugins
targeting grpc-go.
the first real service's .proto once Phase 0 needs it) with the
directory-versioning convention documented.
(gofumpt-clean, matching the "generated assets are LAW" precedent).
task proto:generate,task proto:lint,task proto:checktasksin Taskfile.yml; proto:check regenerates then
git diff --exit-code -- internal/contracts.task proto:generate/lint/checkwired intotask check, insertedafter
go fix ./...and before vet/lint/build.equivalents) mirrored into .github/workflows/deploy.yml's Quality gate
step, since CI does not invoke
task checktoday -- with fetch-depth:0(or an explicit
git fetch origin main) sobuf breaking --againsthas a local main ref to diff against.
buf breakingdemonstrably fails the gate on a deliberately introducedbreaking change (deleted RPC, renamed/removed field) in a smoke test or
manual verification note.
Close reason
Buf v2 protobuf/grpc-go toolchain, generated Gateway contract, proto tasks, CI gate, and breaking-change smoke verification implemented.
Imported from beads
archie-core-8cda.1· GitHub #723 · type task · priority P1 · created 2026-09-05 · closed 2026-09-05