docs(stovepipe): clarify authoritative URI history

Author: mnoah1

api/stovepipe/proto/stovepipe.proto

@@ -67,11 +67,11 @@ message GetRequestHistoryByRequestIDRequest {
     string page_token = 4;
 }
 
-// GetRequestHistoryByURIRequest selects one request history by its exact commit URI.
+// 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 supplied by the selected request.
+    // 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;
@@ -132,7 +132,7 @@ message GetRequestHistoryByRequestIDResponse {
     string next_page_token = 2;
 }
 
-// GetRequestHistoryByURIResponse contains one page of request history.
+// GetRequestHistoryByURIResponse contains one page of the authoritative request's history.
 message GetRequestHistoryByURIResponse {
     // Selected request history and immutable context.
     RequestHistory history = 1;
@@ -149,6 +149,6 @@ service Stovepipe {
     rpc Ingest(IngestRequest) returns (IngestResponse) {}
     // GetRequestHistoryByRequestID returns retained history for one request ID.
     rpc GetRequestHistoryByRequestID(GetRequestHistoryByRequestIDRequest) returns (GetRequestHistoryByRequestIDResponse) {}
-    // GetRequestHistoryByURI returns retained history for one exact commit URI.
+    // GetRequestHistoryByURI returns retained history for an exact commit URI's authoritative request.
     rpc GetRequestHistoryByURI(GetRequestHistoryByURIRequest) returns (GetRequestHistoryByURIResponse) {}
 }

api/stovepipe/protopb/stovepipe.pb.go

@@ -2,7 +2,7 @@
 
 ## Summary
 
-Stovepipe exposes retained request history through queue-scoped point lookups by request ID and exact URI. Both selectors return the same ordered, cursor-paginated history.
+Stovepipe exposes retained request history through queue-scoped point lookups by request ID and exact URI. URI lookup resolves the newest authoritative request for that commit. Both selectors return the same ordered, cursor-paginated history.
 
 The API reads the append-only model defined by [Stovepipe Request Event History](request-event-history.md) directly. It does not replay history into current state or introduce a second persisted history projection. Current commit status remains a separate read concern derived from operational entities rather than request history.
 
@@ -15,7 +15,7 @@ The API supports the same selectors as [SubmitQueue Gateway Request History APIs
 
 Both methods require a queue because Stovepipe storage and authorization are queue-scoped. A selector belonging to another queue is not found rather than resolved across shards.
 
-SubmitQueue's URI method returns several histories because the same change may be submitted repeatedly. Stovepipe ingest permanently deduplicates `(queue, URI)` to one request, so its URI method returns exactly one history. Relaxing that invariant later would require a new plural method rather than changing this method's cardinality in place.
+SubmitQueue's URI method returns several histories because the same change may be submitted repeatedly. Stovepipe's URI method instead returns exactly one history: the request selected by the queue's durable authoritative mapping for that URI. The current insert-once mapping selects the only request; future revalidation advances the mapping to the newest accepted request without changing this API's cardinality. Older attempts remain addressable by request ID, and discovering every attempt can be added later as a separate list API.
 
 ## Representative Contract
 
@@ -83,9 +83,9 @@ Entry IDs and page tokens are opaque. Clients may compare entry IDs and pass pag
 
 Request-ID lookup validates the queue, ID, page size, and optional token; loads the queue's `Request` to validate the selector and supply immutable wrapper context; and lists one bounded page of its `RequestHistoryStore` entries.
 
-URI lookup resolves the existing `RequestURIStore` primary key and delegates to the same paginated request-ID path. It does not scan history by an entry's `URI` field and requires no new storage index. A missing mapping is not found; a mapping whose Request is missing is an internal consistency error.
+URI lookup resolves the authoritative request ID from the existing `RequestURIStore` primary key and delegates to the same paginated request-ID path. Authority is explicit stored state rather than a timestamp comparison. The current mapping is insert-once; supporting revalidation later requires a versioned conditional update that advances it only after the newer Request is durable. It does not scan history by an entry's `URI` field and requires no new storage index. A missing mapping is not found; a mapping whose Request is missing is an internal consistency error.
 
-The request-URI mapping must be repaired and retained with its Request and history. Otherwise URI lookup could lose coverage while request-ID lookup still succeeds. The loaded Request supplies URI, build strategy, and base URI once on the `RequestHistory` wrapper; these immutable values are not duplicated on every entry.
+The request-URI mapping must be repaired and retained with its Request and history. Otherwise URI lookup could lose coverage while request-ID lookup still succeeds. Once a newer request becomes authoritative, a later failure does not fall back to an older successful attempt. The loaded Request supplies URI, build strategy, and base URI once on the `RequestHistory` wrapper; these immutable values are not duplicated on every entry.
 
 ## Public Projection
 
@@ -133,7 +133,7 @@ Request-ID and URI lookup return the same stored entries, ordering, and paginati
 
 The public shape follows SubmitQueue's queue `List` convention: an empty token selects the first page, zero page size selects the server default, and the response returns an opaque `next_page_token` that is empty on the last page. The initial default is 50 entries and the maximum is 200. The controller requests one more entry than the effective page size, returns only the requested page, and issues a token only when the extra entry proves that another page exists.
 
-Pagination uses the immutable keyset `(timestamp_ms ASC, entry_id ASC)`. The versioned token represents the last returned ordering tuple and is bound to the original selector kind and value, queue, and resolved request ID. The binding does not prescribe whether those values are embedded or fingerprinted in the token. Reusing a token with another method, queue, request ID, or URI is invalid. Page size is not bound into the token, so a caller may change it between pages within the server maximum. The controller decodes the public token into the storage contract's typed exclusive cursor; storage implementations never parse wire tokens.
+Pagination uses the immutable keyset `(timestamp_ms ASC, entry_id ASC)`. The versioned token represents the last returned ordering tuple and is bound to the original selector kind and value, queue, and resolved request ID. Binding URI pagination to the resolved request ID keeps an in-progress traversal on the same history if a newer request becomes authoritative between pages. The binding does not prescribe whether those values are embedded or fingerprinted in the token. Reusing a token with another method, queue, request ID, or URI is invalid. Page size is not bound into the token, so a caller may change it between pages within the server maximum. The controller decodes the public token into the storage contract's typed exclusive cursor; storage implementations never parse wire tokens.
 
 Tokens are traversal cursors rather than snapshot handles. A new occurrence ordered after the cursor can appear on a later page. A repair that inserts an older occurrence at or before an already-consumed cursor may be observed only by starting a fresh traversal. This is the paginated form of the API's existing eventual-consistency guarantee: a token prevents duplicates from stable retained entries but does not freeze history while pipeline writers and repair are active.
 
@@ -177,7 +177,7 @@ Rejected because it would add query-by-attribute capability to `RequestHistorySt
 
 ### Return several histories by URI
 
-Rejected while ingest enforces one request per `(queue, URI)`. A repeated field would imply cardinality the domain does not permit and make a future deduplication change silently alter existing responses.
+Rejected because URI lookup answers which request is authoritative for the commit. Returning every attempt would mix audit discovery with one request's independently paginated history. A future attempt-listing API can return request IDs without changing this point lookup.
 
 ### Return every entry in one response