API v3alpha: documentation, conformance, and final hardening

[siavashs]

Parent: #5450

Summary

Track cross-service documentation, conformance, load testing, and final hardening for the experimental v3alpha ConnectRPC API.

Service-specific behavior remains in each service issue. This issue owns the common user-facing guidance and final matrix proving that the delivered service set behaves consistently.

Documentation

Publish generated-client and command-line examples for:

• Connect.
• Connect HTTP GET for side-effect-free methods.
• gRPC-Web.
• Native gRPC and grpcurl.
• Plaintext h2c and configured TLS.
• Root and non-root --web.route-prefix deployments.
• Health and reflection discovery.
• Matchers and OR-of-AND matcher sets.
• Pagination tokens and live-view limitations.
• Structured validation and required-feature errors.
• Capability flags and API v2 limitations.
• Watch initial snapshots, snapshot-complete markers, overflow, resynchronization, and node-local cursor scope.

Document that API v2 remains mounted and identify every enabled v3alpha capability that can create state v2 cannot faithfully represent.

Conformance matrix

Maintain coverage across every registered service and applicable transport for:

• Handler registration, health, and reflection.
• Connect, gRPC-Web, and native gRPC.
• H2c and configured TLS.
• Root and non-root route prefixes.
• Configuration reload.
• HA reads and mutation merge where applicable.
• Feature-disabled and feature-enabled behavior.
• API v1 deprecation and API v2 coexistence.
• Pagination and structured errors.
• Streaming cancellation, lifetime, overflow, and reconnect behavior.

Load and race coverage

Add scenarios for:

• Unary admission saturation.
• Slow request uploads.
• Concurrent list pagination over changing stores.
• Many simultaneous watchers.
• Slow subscribers.
• Queue overflow and resynchronization.
• Cancellation storms.
• Provider, dispatcher, silence-store, reload, and notification-pipeline lock isolation.

Delivery hygiene

• Keep generated protobuf and Connect output reproducible.
• Commit generated code only with corresponding proto source changes.
• Add CHANGELOG.md entries with each user-visible stage.
• Run formatting, lint, short tests, full tests, and relevant race suites before finalizing each service.

Acceptance criteria

• Every published service has generated-client examples and transport documentation.
• Route-prefix, h2c/TLS, health, and reflection behavior is documented.
• Pagination, structured errors, feature flags, v2 limitations, and watch resync are documented.
• The service/transport/feature conformance matrix passes.
• Load and race coverage proves slow clients cannot block API v2 or internal hot paths.
• A second protobuf generation run produces no diff.
• make common-format, make lint, make test-short, and full make test pass for the completed API surface.
• Any deferred alpha capabilities are listed with rationale rather than implied complete.

Related child issues

• Foundation hardening: API v3alpha: harden the ConnectRPC foundation #5478.
• Shared contracts: API v3alpha: add shared contracts and reusable infrastructure #5479.
• Mutation infrastructure: API v3alpha: build stored-mutation watch infrastructure #5480.
• AlertService: API v3alpha: AlertService #5481.
• SilenceService: API v3alpha: SilenceService #5482.
• ReceiverService: API v3alpha: ReceiverService #5483.
• NotificationService: API v3alpha: NotificationService #5484.

[siavashs]

The bundled-browser parity and release-conformance work is tracked in #5493 under #5451. It will add Playwright coverage against a real Alertmanager binary for /ui/ and non-root route prefixes, generated Connect unary/mutations, watch reconnect/resnapshot, accessibility, hostile/UTF-8 content, asset caching/compression, and dual-UI release artifacts.