feat(stovepipe): add request history protobuf contract

api/stovepipe/proto/stovepipe.proto

@@ -54,11 +54,101 @@ message IngestResponse {
     string id = 1;
 }
 
+// GetRequestHistoryByRequestIDRequest selects one request history by the ID
+// returned from Ingest.
+message GetRequestHistoryByRequestIDRequest {
+    // Logical queue containing the request.
+    string queue = 1;
+    // Globally unique request identifier returned from Ingest.
+    string request_id = 2;
+    // Maximum entries to return. Zero selects the server default.
+    int32 page_size = 3;
+    // Opaque continuation token. Empty selects the first page.
+    string page_token = 4;
+}
+
+// GetRequestHistoryByURIRequest selects the authoritative request history for an exact commit URI.
+message GetRequestHistoryByURIRequest {
+    // Logical queue containing the request.
+    string queue = 1;
+    // Exact VCS-agnostic commit URI whose authoritative request is selected.
+    string uri = 2;
+    // Maximum entries to return. Zero selects the server default.
+    int32 page_size = 3;
+    // Opaque continuation token. Empty selects the first page.
+    string page_token = 4;
+}
+
+// ValidationResult is the immutable validation verdict for one scope.
+message ValidationResult {
+    // Degree measures how broken the scope is on [0.0, 1.0]. Zero is fully
+    // green and one is fully broken.
+    double degree = 1;
+}
+
+// HistoryEntry is one retained request state or lifecycle event.
+message HistoryEntry {
+    // Opaque stable identity of this logical occurrence within the request.
+    string entry_id = 1;
+    // Occurrence time in Unix milliseconds.
+    int64 timestamp_ms = 2;
+    // Exactly one occurrence kind is populated.
+    oneof occurrence {
+        // Durable request state reached by the request.
+        string request_state = 3;
+        // Event that occurred without changing the request state.
+        string event = 4;
+    }
+    // Newer request that caused a superseded state. Empty when not applicable.
+    string superseded_by_request_id = 5;
+    // Build associated with the occurrence. Empty when no build applies.
+    string build_id = 6;
+    // Stable domain reason for a terminal request outcome. Empty otherwise.
+    string outcome_reason = 7;
+    // Recorded validation verdict. Present only when the occurrence established
+    // an immutable validation fact.
+    ValidationResult result = 8;
+}
+
+// RequestHistory contains immutable request context and one ordered page of entries.
+message RequestHistory {
+    // Globally unique request identifier.
+    string request_id = 1;
+    // VCS-agnostic commit URI validated by the request.
+    string uri = 2;
+    // Validation scope selected for the request.
+    string build_strategy = 3;
+    // Baseline URI for incremental validation. Empty for a full build.
+    string base_uri = 4;
+    // Entries ordered by occurrence time and stable entry identity.
+    repeated HistoryEntry entries = 5;
+}
+
+// GetRequestHistoryByRequestIDResponse contains one page of request history.
+message GetRequestHistoryByRequestIDResponse {
+    // Selected request history and immutable context.
+    RequestHistory history = 1;
+    // Opaque continuation token. Empty on the final page.
+    string next_page_token = 2;
+}
+
+// GetRequestHistoryByURIResponse contains one page of the authoritative request's history.
+message GetRequestHistoryByURIResponse {
+    // Selected request history and immutable context.
+    RequestHistory history = 1;
+    // Opaque continuation token. Empty on the final page.
+    string next_page_token = 2;
+}
+
 // Stovepipe provides the Stovepipe API.
 service Stovepipe {
     // Ping returns a response indicating the service is alive
     rpc Ping(PingRequest) returns (PingResponse) {}
     // Ingest admits a queue's newly observed commit into the validation pipeline and returns
     // the minted request ID. The caller hands off asynchronously; validation happens later.
     rpc Ingest(IngestRequest) returns (IngestResponse) {}
+    // GetRequestHistoryByRequestID returns retained history for one request ID.
+    rpc GetRequestHistoryByRequestID(GetRequestHistoryByRequestIDRequest) returns (GetRequestHistoryByRequestIDResponse) {}
+    // GetRequestHistoryByURI returns retained history for an exact commit URI's authoritative request.
+    rpc GetRequestHistoryByURI(GetRequestHistoryByURIRequest) returns (GetRequestHistoryByURIResponse) {}
 }