feat(api): surface feed last-updated as update_time on catalogue resources

The upstream feeds carry a last-updated timestamp the contract was discarding:
beverage files have a per-category top-level `timestamp`, and the registry has a
top-level `last_updated`. Expose them as OUTPUT_ONLY update_time:

- Drink.update_time / Producer.update_time  <- beverage file timestamp (per
  festival category; the file is the unit of change, so items in a category
  share the value)
- Festival.update_time                      <- registry last_updated (registry-wide)

Document the freshness/polling model in the proto README: conditional re-fetch
(If-None-Match/304) keyed off update_time, not item-level delta (the feeds are
whole-file snapshots, so per-drink change attribution isn't available).

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

Author: claude

proto/README.md

@@ -51,6 +51,36 @@ service, graduate at different times while staying under
 
 See `buf.yaml` for the step-by-step promotion path.
 
+### Freshness & polling
+
+Catalogue data changes during a live festival (drink availability especially)
+and between festivals (new festivals). Clients poll the List endpoints to stay
+current; the contract carries the freshness signal the upstream feeds already
+provide:
+
+- Each beverage feed file (`{festival}/{category}.json`) has a top-level
+  `timestamp` (last-updated). It surfaces as **`Drink.update_time`** and
+  **`Producer.update_time`** — granularity is per festival category (the file is
+  the unit of change), so all items from one category share the value. The feed
+  does **not** expose per-drink change times.
+- The registry feed has a top-level `last_updated`, surfaced as
+  **`Festival.update_time`** (registry-wide).
+
+The efficient polling model is therefore **conditional re-fetch**, not item-level
+delta sync:
+
+1. Poll with HTTP `If-None-Match`/`If-Modified-Since`; an unchanged collection
+   returns `304 Not Modified` and transfers nothing.
+2. When it has changed, re-pull the (small, bounded) list and use `update_time`
+   to confirm/raise the client's "as of" marker and drive "updated N ago" UI.
+
+Item-level delta (`update_time > T` filtering) is intentionally **not** offered:
+the feeds are whole-file snapshots, so the server cannot attribute a change to a
+single drink. Re-fetch keyed off the per-category `update_time` matches the data's
+real change granularity. (Realising the `304` path needs the worker to honour
+conditional requests and shorten the drinks `Cache-Control` TTL — tracked
+separately from this contract.)
+
 ## Layout
 
 ```

proto/cambeerfestival/festival/v1alpha/drink.proto

@@ -5,6 +5,7 @@ package cambeerfestival.festival.v1alpha;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
 
 // A single beverage available at a festival, flattened from the underlying
 // data feed's producer/product structure. Product details live here; the
@@ -72,6 +73,14 @@ message Drink {
   // 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];
+
+  // When this drink's source dataset was last updated, taken from the feed
+  // file's top-level `timestamp`. Granularity is per festival category (the
+  // feed file is the unit of change), so all drinks from the same category
+  // share this value — the feed does not expose per-drink change times. Use it,
+  // alongside HTTP Last-Modified/ETag, to detect whether a category's data
+  // changed and decide whether to re-poll.
+  google.protobuf.Timestamp update_time = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // A lightweight pointer from a Drink to its Producer: the producer's resource

proto/cambeerfestival/festival/v1alpha/festival.proto

@@ -5,6 +5,7 @@ package cambeerfestival.festival.v1alpha;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
 import "google/type/date.proto";
 import "google/type/latlng.proto";
 
@@ -80,4 +81,11 @@ message Festival {
 
   // Donation URL for the charity partner. Empty when none.
   string charity_donation_uri = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // When the festival registry/config was last updated, taken from the registry
+  // feed's top-level `last_updated`. This reflects festival *metadata*
+  // freshness and is registry-wide (the same across festivals in one response);
+  // per-drink and per-producer data freshness is on those resources'
+  // update_time.
+  google.protobuf.Timestamp update_time = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
 }

proto/cambeerfestival/festival/v1alpha/producer.proto

@@ -5,6 +5,7 @@ package cambeerfestival.festival.v1alpha;
 
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
 
 // A producer (brewery, cidery, meadery, etc.) at a festival.
 //
@@ -39,4 +40,9 @@ message Producer {
 
   // Free-text notes about the producer. Empty when unset.
   string notes = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // When this producer's source dataset was last updated, taken from the feed
+  // file's top-level `timestamp` (producers come from the same category feed
+  // files as drinks). Granularity is per festival category, not per producer.
+  google.protobuf.Timestamp update_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
 }