# kmsvc-proto — shared proto contract implementation plan

## Context

Third sibling repo alongside `kafaka_management_service` (server), `kmsvc-sdk` (Go client SDK), and `kmsvc-cli` (CLI). Holds the `kafkamgmt.v1` proto definitions as the single source of truth, so the server and the SDK don't generate code from two independently-drifting copies of the same `.proto` file.

**Scope is intentionally narrow**: this repo ships `.proto` source + buf lint/breaking-change config only — no generated code, no language-specific runtime deps. Each consumer (server, SDK) submodules this repo and runs its own `buf generate` into its own internal package, using its own pinned plugin/runtime versions. This avoids forcing the server and the SDK to agree on the same generated-code/runtime version (protobuf-go, grpc-gateway) — only the wire contract is shared, not the generated artifacts.

## Repo layout

```
kmsvc-proto/
  buf.yaml                         # lint (DEFAULT) + breaking-change (FILE) rules, same as today's server config
  proto/kafkamgmt/v1/queue_service.proto
  CHANGELOG.md                      # human-readable log of wire-contract changes, one entry per tag
  .forgejo/workflows/ci.yaml        # buf lint + buf breaking against the previous tag
```

No `buf.gen.yaml` here — codegen output/plugins are each consumer's concern, not this repo's.

## Implementation steps

### Step 1 — Seed the repo
- Move `kafaka_management_service/proto/kafkamgmt/v1/queue_service.proto` and `buf.yaml` into this repo verbatim (git history doesn't follow across repos; note the origin commit in the first commit message for traceability).
- **Verify**: `buf lint` and `buf build` run clean from this repo's root.

### Step 2 — Breaking-change gate
- Forgejo Actions workflow: on every PR, `buf breaking --against '.git#branch=main'` so an accidental incompatible field/RPC change is caught before merge, not discovered by a downstream consumer.
- **Verify**: a real PR introducing a breaking change (e.g. renumbering a field) fails the check; a compatible addition (new optional field) passes.

### Step 3 — Tagging convention
- Semantic version tags (`v1.0.0`, `v1.1.0`, ...): **minor** bump for additive/compatible changes, **major** bump for anything `buf breaking` would have flagged (only ever done deliberately, never silently). `CHANGELOG.md` gets one entry per tag.
- **Verify**: tag `v1.0.0` once Step 1+2 are in place and the current contract (the 6 data-plane RPCs already defined) is confirmed stable.

### Step 4 — Wire into the server repo
- In `kafaka_management_service`: replace the in-repo `proto/` directory with a git submodule at the same path, pointed at this repo's `v1.0.0` tag; `buf.gen.yaml` and the existing `make proto`/`buf generate` flow are otherwise unchanged (still generates into `internal/api/v1`).
- **Verify**: `git submodule update --init && buf generate && go build ./...` in the server repo produces identical generated output to what's committed today (diff should be empty other than the submodule pointer file).

### Step 5 — Wire into kmsvc-sdk
- `kmsvc-sdk` adds this repo as a submodule at `proto/`, pinned to the same tag the server currently uses, with its own `buf.gen.yaml` generating into `internal/genapi/` (per `kmsvc-sdk/PLAN.md` step 1).
- **Verify**: both repos' generated code, despite being produced independently, satisfy the same wire format — confirmed implicitly by an SDK-vs-server integration test (SDK client talks to a real running server) once both exist.

## Acceptance criteria
- [ ] `buf lint`/`buf build` pass from a clean checkout.
- [ ] `buf breaking` CI gate blocks incompatible changes on PRs, verified by a real failing PR.
- [ ] `v1.0.0` tag exists and matches the contract currently live in `kafaka_management_service`.
- [ ] Server repo's submodule swap (step 4) produces byte-identical generated code to its current committed output.
- [ ] `kmsvc-sdk`'s codegen against the same tag succeeds (step 5 of this plan / step 1 of `kmsvc-sdk/PLAN.md`).

## Sequencing note
Do this repo's steps 1–3 before starting `kmsvc-sdk` step 1 (SDK needs something to submodule). Step 4 (migrating the server repo) can happen any time after step 3 — it's a refactor of already-working code, not a blocker for the SDK/CLI work, so it can be deferred or done opportunistically without holding up `kmsvc-sdk`/`kmsvc-cli` progress.