[Initiative] gRPC GitEvent Notification Stream from gitstore-git-service to gitstore-api

[juliuskrah]

Summary

Define the gRPC notification stream from gitstore-git-service to gitstore-api so the API can react to Git changes without WebSockets. The stream should carry commit/ref transition events and provide the control-plane trigger for sync and admission handling.

In Scope

• Define a GitEvent gRPC payload contract for ref changes, old/new SHA values, and event type
• Implement a server-streaming notification path from git-service to API
• Route push and tag events through the stream so the API can decide whether to hydrate draft/latest state or promote live state
• Add contract tests for event delivery, reconnect behavior, and event typing
• Document the event flow and operational expectations across the two services

Out of Scope

• The hydration and live-promotion logic itself (tracked separately)
• Replacing Git wire protocol handling
• UI notifications or browser-based realtime updates
• Authentication/authorization policy design

Acceptance Criteria

• gitstore-git-service emits ref-change events to gitstore-api over gRPC
• Event payloads include ref, old SHA, new SHA, and event type
• API consumers can distinguish push vs tag notifications
• Lost connection / reconnect behavior is covered by automated tests
• Event documentation explains how stream notifications feed Sync Controller processing
• No WebSocket dependency is required for control-plane notifications

Implementation Notes

This stream is the control-plane equivalent of a watch mechanism: the git-service tells the API that Git state changed, but the API remains responsible for interpreting and materializing that change. Keeping the notification channel on gRPC preserves a clean service boundary and aligns with the rest of the Git-service decoupling work. The stream should be minimal and event-oriented, not a transport for business logic.

Dependencies

• Depends on: [Initiative] Decouple API from Git Storage via gRPC Git Service #65 (gRPC Git Service boundary)
• Related: [Initiative] Tag-Gated Sync Controller for Atomic Release Promotion #132 (tag-gated sync controller), [Initiative] Controller Watch API with resourceVersion Resume #131 (watch API / resourceVersion resume), [Initiative] API Admission Controller (Validating Phase Only) #123 (admission validation)

[juliuskrah]

Supersedes #66