chore(proto): tighten breaking detection and gate AIP lint in CI

The "my festival" API is HTTP/JSON-only (no gRPC server), so a JSON
field-name change breaks real clients even when the wire format is
unchanged. Switch buf breaking detection from WIRE to WIRE_JSON so those
changes are caught now rather than deferred to v1.

Add the AIP design linter (api-linter) to the CI proto job with
--set-exit-status so design-level regressions buf's STANDARD ruleset
doesn't cover actually gate merges; mirror the flag in the proto:api-lint
mise task. Pin buf (1.70.0) and api-linter (2.3.1) in dev and CI so local
and CI results agree.

Fix the stale buf.yaml lint comment (Delete returns the DrinkEntry
tombstone per AIP-164, not google.protobuf.Empty) and drop the now-dead
empty.proto breaking-ignore entry.

Author: claude

.github/workflows/ci.yml

@@ -99,11 +99,10 @@ jobs:
           mapfile -t SH_FILES < <(find . -name '*.sh' -not -path './.git/*' -not -path './.mise/*' -not -path '*/node_modules/*' | sort)
           [[ ${#SH_FILES[@]} -gt 0 ]] && shfmt -d -i 0 -ci "${SH_FILES[@]}"
 
-  # Lint proto files and check for breaking changes against main.
-  # buf breaking runs on PRs only (bufbuild/buf-action skips it on push to main
-  # where the change is already merged). FILE stability level (configured in
-  # proto/buf.yaml) is appropriate for v1alpha; switch to WIRE_JSON_COMPATIBLE
-  # when the API graduates to v1.
+  # Lint proto files, check for breaking changes against main, and run the
+  # AIP design linter. buf breaking runs on PRs only (bufbuild/buf-action skips
+  # it on push to main where the change is already merged). buf.yaml uses
+  # WIRE_JSON breaking detection because the transport is HTTP/JSON.
   proto:
     needs: changes
     runs-on: ubuntu-latest
@@ -118,11 +117,34 @@ jobs:
 
       - uses: bufbuild/buf-action@v1
         with:
+          version: 1.70.0
           input: proto
           push: false
           pr_comment: false
           breaking_against: "https://github.com/${{ github.repository }}.git#branch=main,subdir=proto"
 
+      # AIP design lint (googleapis/api-linter) — the design-level rules buf's
+      # STANDARD ruleset doesn't cover. Mirrors the proto:api-lint mise task.
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: stable
+
+      - name: Install api-linter
+        run: go install github.com/googleapis/api-linter/v2/cmd/api-linter@v2.3.1
+
+      - name: AIP design lint
+        working-directory: proto
+        run: |
+          buf build -o /tmp/cambeerfestival.pb
+          api-linter \
+            --config .api-linter.yaml \
+            --descriptor-set-in=/tmp/cambeerfestival.pb \
+            --set-exit-status \
+            cambeerfestival/myfestival/v1alpha/my_festival_service.proto \
+            cambeerfestival/myfestival/v1alpha/drink_entry.proto \
+            cambeerfestival/myfestival/v1alpha/drink_summary.proto
+
   # Analyze code in parallel with tests so builds can start sooner
   analyze:
     needs: changes

mise.dev.toml

@@ -16,14 +16,14 @@
 
 [tools]
 watchexec = "2.5.1"
-buf = "latest"
+buf = "1.70.0"
 
 # --- Protobuf / OpenAPI (API contract is proto-first; see proto/README.md) ---
-# buf and api-linter live here (dev-only) while the API design is still in flux.
-# Move both to base mise.toml when the API stabilises and proto tasks enter CI.
-# Move it to base mise.toml once the resource shapes and method signatures
-# have stabilised and the linter output is expected to stay clean in CI.
-"github:googleapis/api-linter" = "latest"
+# buf and api-linter live here for local dev. CI runs the equivalent checks in
+# the `proto` job (buf-action + api-linter via go install), so these versions
+# are pinned to match CI. Move both to base mise.toml if the toolchain is ever
+# needed by base (non-dev) tasks.
+"github:googleapis/api-linter" = "2.3.1"
 
 [tasks."proto:lint"]
 description = "Lint the protobuf API contract (buf STANDARD ruleset)"
@@ -86,6 +86,7 @@ buf build -o /tmp/cambeerfestival.pb
 api-linter \
   --config .api-linter.yaml \
   --descriptor-set-in=/tmp/cambeerfestival.pb \
+  --set-exit-status \
   cambeerfestival/myfestival/v1alpha/my_festival_service.proto \
   cambeerfestival/myfestival/v1alpha/drink_entry.proto \
   cambeerfestival/myfestival/v1alpha/drink_summary.proto

proto/buf.yaml

@@ -7,16 +7,20 @@ lint:
   use:
     - STANDARD
   except:
-    # AIP-131/134: Get and Update return the resource itself, and Delete
-    # returns google.protobuf.Empty — both intentionally diverge from buf's
-    # "<Method>Response" / unique-response defaults. Google's own APIs do the same.
+    # AIP-131/134/164: Get, Update, and Delete all return the DrinkEntry
+    # resource itself (Delete is a soft delete that returns the tombstone), so
+    # one response message is shared across methods and none match buf's
+    # "<Method>Response" naming default. Google's own APIs do the same.
     - RPC_RESPONSE_STANDARD_NAME
     - RPC_REQUEST_RESPONSE_UNIQUE
 breaking:
   use:
     - FILE
-    - WIRE
-  # WIRE catches field-number renumbering and field-type changes on the wire.
+    - WIRE_JSON
+  # WIRE_JSON is a superset of WIRE: it catches field-number renumbering and
+  # field-type changes (WIRE) AND JSON field-name changes. The transport is
+  # HTTP/JSON (we run no gRPC server), so renaming a field is breaking for real
+  # clients even when the wire format is unchanged — WIRE alone would miss it.
   # FILE catches deleted files and moved definitions.
   #
   # Promotion path:
@@ -25,8 +29,6 @@ breaking:
   #     No buf.yaml changes needed — ignore_unstable_packages stays absent so
   #     beta breaking changes are caught from day one.
   #   v1beta1 → v1: copy package to cambeerfestival.myfestival.v1 and delete
-  #     beta. Switch breaking.use to WIRE_JSON_COMPATIBLE here (superset of
-  #     WIRE; also checks JSON field name stability). Add ignore_unstable_packages:
-  #     true only if a new v2alpha package coexists with stable v1.
-  ignore:
-    - google/protobuf/empty.proto
+  #     beta. No breaking-config change needed (already WIRE_JSON). Add
+  #     ignore_unstable_packages: true only if a new v2alpha package coexists
+  #     with stable v1.