feat(api): add Producer resource and slim Drink's producer embed

The data feed is producer-keyed, so producer metadata is naturally normalised
(once per producer). The previous Drink.producer embed re-duplicated a brewery's
location/founding-year/notes across every one of its drinks on the wire.

Model Producer as a first-class resource (festivals/{f}/producers/{p}) with
Get/List, and replace Drink's full embed with a ProducerReference (producer
resource name + display_name denormalised only for cheap card/search rendering).
This keeps brewery detail normalised, matches the feed's shape, and enables
brewery-directory browsing.

buf lint, AIP api-linter, and OpenAPI generation all pass.

Author: claude

mise.dev.toml

@@ -87,6 +87,7 @@ api-linter \
   --config .api-linter.yaml \
   --descriptor-set-in=/tmp/cambeerfestival.pb \
   cambeerfestival/festival/v1alpha/festival.proto \
+  cambeerfestival/festival/v1alpha/producer.proto \
   cambeerfestival/festival/v1alpha/drink.proto \
   cambeerfestival/festival/v1alpha/catalog_service.proto \
   cambeerfestival/festival/v1alpha/drink_entry.proto \

proto/README.md

@@ -56,7 +56,8 @@ proto/
 ├── .api-linter.yaml          # AIP linter suppressions (see comments in file)
 └── cambeerfestival/festival/v1alpha/
     ├── festival.proto            # Festival — festival metadata (canonical)
-    ├── drink.proto               # Drink — catalogue drink (canonical) + Producer
+    ├── producer.proto            # Producer — brewery/cidery (canonical)
+    ├── drink.proto               # Drink (canonical) + ProducerReference
     ├── catalog_service.proto     # CatalogService — read-only Get/List
     ├── drink_entry.proto         # DrinkEntry — caller personal state per drink
     ├── drink_summary.proto       # DrinkSummary — public aggregates per drink
@@ -65,15 +66,23 @@ proto/
 
 ## Catalogue resource model (AIP-121/122)
 
-`CatalogService` defines the shared, read-only catalogue. All four RPCs are
-reads — catalogue data is published out-of-band via the festival data feeds, so
-there are no create/update/delete methods and every data field is `OUTPUT_ONLY`.
+`CatalogService` defines the shared, read-only catalogue. Every RPC is a read —
+catalogue data is published out-of-band via the festival data feeds, so there
+are no create/update/delete methods and every data field is `OUTPUT_ONLY`.
 
 | Resource | Name pattern | Methods |
 | --- | --- | --- |
 | `Festival` | `festivals/{f}` | Get, List |
+| `Producer` | `festivals/{f}/producers/{p}` | Get, List |
 | `Drink` | `festivals/{f}/drinks/{d}` | Get, List (filter, order_by, paginated) |
 
+`Producer` is a first-class resource so producer metadata stays normalised — the
+feed is producer-keyed, so a brewery's location/founding-year/notes live once on
+the `Producer`, and each `Drink` carries a `ProducerReference` (the producer
+resource name plus its `display_name`, denormalised only for cheap card/search
+rendering) rather than embedding the full record. Hydrate the producer directory
+with `ListProducers`, or fetch one with `GetProducer`.
+
 `Festival` and `Drink` are defined **canonically here**. `DrinkEntry`'s pattern
 references them as parent types; because everything shares one package those
 references resolve directly, so no `resource_definition` stubs are needed (a type

proto/cambeerfestival/festival/v1alpha/catalog_service.proto

@@ -5,6 +5,7 @@ package cambeerfestival.festival.v1alpha;
 
 import "cambeerfestival/festival/v1alpha/drink.proto";
 import "cambeerfestival/festival/v1alpha/festival.proto";
+import "cambeerfestival/festival/v1alpha/producer.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
@@ -63,6 +64,24 @@ service CatalogService {
     option (google.api.http) = {get: "/v1alpha/{name=festivals/*/drinks/*}"};
     option (google.api.method_signature) = "name";
   }
+
+  // --- Producers ------------------------------------------------------------
+  // List the producers (breweries, cideries, etc.) at a festival.
+  //
+  // One call hydrates the festival's producer directory, e.g. to resolve the
+  // ProducerReference on each drink or to power A–Z brewery browsing. The
+  // server default returns all producers in a single page; set page_size to
+  // paginate.
+  rpc ListProducers(ListProducersRequest) returns (ListProducersResponse) {
+    option (google.api.http) = {get: "/v1alpha/{parent=festivals/*}/producers"};
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Get a single producer.
+  rpc GetProducer(GetProducerRequest) returns (Producer) {
+    option (google.api.http) = {get: "/v1alpha/{name=festivals/*/producers/*}"};
+    option (google.api.method_signature) = "name";
+  }
 }
 
 // Request message for ListFestivals.
@@ -112,7 +131,8 @@ message ListDrinksRequest {
   string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
 
   // AIP-160 filter expression. Supported fields: category, style, dispense,
-  // abv, vegan, producer.producer_id. Example: category = "beer" AND abv < 5.0.
+  // abv, vegan, producer.producer (the producer resource name). Example:
+  // category = "beer" AND abv < 5.0.
   string filter = 4 [(google.api.field_behavior) = OPTIONAL];
 
   // AIP-132 ordering, e.g. "display_name" or "abv desc". Supported fields:
@@ -140,3 +160,40 @@ message GetDrinkRequest {
     (google.api.resource_reference).type = "api.cambeerfestival.app/Drink"
   ];
 }
+
+// Request message for ListProducers.
+message ListProducersRequest {
+  // Parent festival: festivals/{festival}.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference).child_type = "api.cambeerfestival.app/Producer"
+  ];
+
+  // Maximum number of producers to return. The server default returns all
+  // producers for the festival in a single page. Set explicitly to paginate.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Page token from a previous ListProducers response.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for ListProducers.
+message ListProducersResponse {
+  // The producers for this page.
+  repeated Producer producers = 1;
+
+  // Token for the next page; empty when there are no more results.
+  string next_page_token = 2;
+
+  // Total number of producers at this festival.
+  int32 total_size = 3;
+}
+
+// Request message for GetProducer.
+message GetProducerRequest {
+  // Resource name: festivals/{festival}/producers/{producer}.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference).type = "api.cambeerfestival.app/Producer"
+  ];
+}

proto/cambeerfestival/festival/v1alpha/drink.proto

@@ -7,8 +7,10 @@ import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 
 // A single beverage available at a festival, flattened from the underlying
-// data feed's producer/product structure into the composite the app consumes
-// (product details plus the producing brewery/cidery).
+// data feed's producer/product structure. Product details live here; the
+// producing brewery/cidery is referenced by resource name (see
+// ProducerReference) rather than embedded, so producer metadata is not
+// duplicated across every one of its drinks.
 //
 // This is the canonical definition of the `Drink` resource that the "my
 // festival" API's DrinkEntry (festivals/{f}/drinks/{d}/entry) and DrinkSummary
@@ -67,29 +69,26 @@ message Drink {
   // Whether the drink is vegan. Absent when the producer did not declare it.
   optional bool vegan = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // The brewery/cidery/meadery that makes this drink.
-  Producer producer = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // The brewery/cidery/meadery that makes this drink, as a reference to the
+  // Producer resource plus its display name for cheap list rendering.
+  ProducerReference producer = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// The producer of a drink (brewery, cidery, meadery, etc.). Embedded in Drink
-// rather than modelled as its own resource for now; it may be promoted to a
-// top-level catalogue resource (festivals/{festival}/producers/{producer})
-// if brewery-scoped browsing needs stable resource names.
-message Producer {
-  // The producer's id within the festival data feed.
-  string producer_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
-
-  // Producer name, e.g. "Milton Brewery".
+// A lightweight pointer from a Drink to its Producer: the producer's resource
+// name plus its display name denormalised for cheap list rendering (drink
+// cards and search). The authoritative producer record — location, founding
+// year, notes — is the Producer resource; fetch it with GetProducer or hydrate
+// the festival's producers in one call via ListProducers.
+message ProducerReference {
+  // Resource name of the producer: festivals/{festival}/producers/{producer}.
+  string producer = 1 [
+    (google.api.field_behavior) = OUTPUT_ONLY,
+    (google.api.resource_reference).type = "api.cambeerfestival.app/Producer"
+  ];
+
+  // Producer name, e.g. "Milton Brewery". Denormalised from the Producer
+  // resource so drink cards and search need no second lookup.
   string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
-
-  // Where the producer is based, e.g. "Cambridge". Empty when unknown.
-  string location = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
-
-  // Year the producer was founded. Absent when unknown.
-  optional int32 founding_year = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
-
-  // Free-text notes about the producer. Empty when unset.
-  string notes = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Availability state for a drink, ordered from most to least available.

proto/cambeerfestival/festival/v1alpha/producer.proto

@@ -0,0 +1,42 @@
+// Producer catalogue resource for the read-only "festival" API.
+syntax = "proto3";
+
+package cambeerfestival.festival.v1alpha;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+
+// A producer (brewery, cidery, meadery, etc.) at a festival.
+//
+// The underlying data feed is producer-keyed — each producer carries its
+// metadata once, with its drinks nested underneath. Modelling Producer as a
+// first-class resource keeps that normalisation: a producer's name, location,
+// founding year and notes live here exactly once, and each Drink references its
+// producer by resource name instead of embedding a copy. The catalogue is
+// read-only: every field except the resource name is server-populated
+// (OUTPUT_ONLY).
+//
+// Note: producer ids are NOT guaranteed stable across festival years.
+message Producer {
+  option (google.api.resource) = {
+    type: "api.cambeerfestival.app/Producer"
+    pattern: "festivals/{festival}/producers/{producer}"
+    singular: "producer"
+    plural: "producers"
+  };
+
+  // Resource name: festivals/{festival}/producers/{producer}.
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Producer name, e.g. "Milton Brewery".
+  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Where the producer is based, e.g. "Cambridge". Empty when unknown.
+  string location = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Year the producer was founded. Absent when unknown.
+  optional int32 founding_year = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Free-text notes about the producer. Empty when unset.
+  string notes = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+}