feat: add resourceVersion to Freight, Stage, Warehouse list and watch endpoints

[jessesuen]

Summary

• New proto fields: Added resource_version to the List response messages for Stages, Warehouses, and Freight (ListStagesResponse, ListWarehousesResponse, QueryFreightResponse), and to the Watch request messages (WatchStagesRequest, WatchWarehousesRequest, WatchFreightRequest).
• Backend — List handlers: The ConnectRPC and REST List handlers now return a meaningful resourceVersion in responses. Because the controller-runtime cached client always returns "0" for the list-level ResourceVersion, a new effectiveResourceVersion helper falls back to max(item.ResourceVersion) across all returned objects when the list-level value is absent or "0". This yields a valid lower-bound resource version without bypassing the cache.
• Backend — Watch handlers: The ConnectRPC and REST Watch handlers for Stages, Warehouses, and Freight now accept an optional resourceVersion parameter and forward it to the underlying Kubernetes Watch call. When provided, Kubernetes sends only events newer than that version, eliminating the full ADDED-event replay that previously occurred on every Watch connection.
• REST API: The REST queryFreight response now includes a top-level resourceVersion field alongside groups, mirroring the ConnectRPC behavior.

Motivation

This enables the standard Kubernetes list-then-watch pattern: a client can call a List endpoint, record the returned resourceVersion, then start a Watch from that exact point to receive all subsequent changes without gaps or redundant initial events.

Tests

• Tests: New unit tests for effectiveResourceVersion, and additional integration-style tests for ListStages and QueryFreight covering the resource version passthrough and fallback behaviors.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	0a0b864
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/69eb1d9db617b3000820c970
😎 Deploy Preview	https://deploy-preview-6156.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

❌ Patch coverage is 66.26506% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.69%. Comparing base (596be3d) to head (0a0b864).

Files with missing lines	Patch %	Lines
pkg/server/list_warehouses_v1alpha1.go	33.33%	7 Missing and 1 partial ⚠️
pkg/server/list_stages_v1alpha1.go	82.60%	3 Missing and 1 partial ⚠️
pkg/server/query_freights_v1alpha1.go	80.95%	4 Missing ⚠️
pkg/server/watch_freight_v1alpha1.go	33.33%	3 Missing and 1 partial ⚠️
pkg/server/watch_stages_v1alpha1.go	0.00%	3 Missing and 1 partial ⚠️
pkg/server/watch_warehouses_v1alpha1.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6156   +/-   ##
=======================================
  Coverage   57.69%   57.69%           
=======================================
  Files         474      475    +1     
  Lines       40499    40558   +59     
=======================================
+ Hits        23365    23401   +36     
- Misses      15739    15758   +19     
- Partials     1395     1399    +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jessesuen]

This was an interesting discovery during end-to-end testing.

The Kargo API uses the controller-runtimes cached client for list requests. Before this helper, the List call had blindly carried over the resourceVersion from the cached client's List response. But that value was always 0, and so the result had no benefit for UI performance since the subsequent Watch would replay all objects.

This helper allows us to continue using the cached client while benefiting from a smaller payload in the subsequent Watch call by using the max resourceVersion from the cached list. In my testing/research, this works as advertised, but need to proceed cautiously here.