Add a bit more precision to docs, plus philosophy

api.md

@@ -91,7 +91,9 @@ Submits a transaction to be committed. The transaction consists of read precondi
   // If not committed, a more recent version that the client can use to retry.
   "version": 123456,
   // The unique ID of the leader at this version.
-  "leader_id": "abcdefg"
+  "leader_id": "abcdefg",
+  // Echo back the request_id if it was provided in the original request
+  "request_id": "abcdefg"
 }
 ```
 
@@ -169,7 +171,7 @@ The response is a stream of events compliant with the SSE protocol.
 
 ```
 event: transaction
-data: {"request_id":"abcdefg","version":123456,"timestamp":"2025-08-07T20:27:42.555Z","leader_id":"abcdefg","operations":[...]}
+data: {"request_id":"abcdefg","version":123456,"prev_version":123455,"timestamp":"2025-08-07T20:27:42.555Z","leader_id":"abcdefg","operations":[...]}
 
 ```
 
@@ -194,6 +196,8 @@ data: {"committed_version":123456,"leader_id":"abcdefg"}
 
 1. **Leader Changes & Reconnection**: When `durable=false`, if the leader changes, clients **must** discard all of that leader's `transaction` events received after their last-seen `checkpoint` event. They must then manually reconnect (as the server connection will likely be terminated) and restart the subscription by setting the `after` query parameter to the version specified in that last-known checkpoint. Clients should implement a randomized exponential backoff strategy (backoff with jitter) when reconnecting.
 
+1. **Gap Detection**: Each `transaction` event includes a `prev_version` field linking to the previous transaction version, forming a linked list. Clients can detect gaps in the transaction stream by checking that each transaction's `prev_version` matches the previous transaction's `version`. This ensures gapless transitions between historical data from S3 and live events from the server.
+
 1. **Connection Handling & Errors**: The server may periodically send `keepalive` comments to prevent idle timeouts on network proxies. The server will buffer unconsumed data up to a configurable limit; if the client falls too far behind, the connection will be closed. If the `after` version has been truncated from the log, this endpoint will return a standard `410 Gone` HTTP error instead of an event stream.
 
 ## `PUT /v1/retention/<policy_id>`