Paginate by creation time instead of key order

Clients often need to fetch recent payments or entries without
iterating over the entire keyspace. Ordering by created_at
lets callers retrieve the newest records first and stop early,
which is not possible with lexicographic key ordering.

The page token now encodes (created_at, key) so the cursor
remains unique even when multiple rows share the same timestamp.
A composite index on (user_token, store_id, created_at, key)
keeps the query efficient, and a migration back-fills any NULL
created_at values and adds the NOT NULL constraint.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: benthecarman

proto/vss.proto

@@ -210,20 +210,16 @@ message ListKeyVersionsRequest {
 // Server response for `ListKeyVersions` API.
 message ListKeyVersionsResponse {
 
-  // Fetched keys and versions.
+  // Fetched keys and versions, ordered by creation time (newest first) ties broken by key (alphabetically).
   // Even though this API reuses the `KeyValue` struct, the `value` sub-field will not be set by the server.
   repeated KeyValue key_versions = 1;
 
   // `next_page_token` is a pagination token, used to retrieve the next page of results.
   // Use this value to query for next-page of paginated `ListKeyVersions` operation, by specifying
   // this value as the `page_token` in the next request.
   //
-  // If `next_page_token` is empty (""), then the "last page" of results has been processed and
-  // there is no more data to be retrieved.
-  //
-  // If `next_page_token` is not empty, it does not necessarily mean that there is more data in the
-  // result set. The only way to know when you have reached the end of the result set is when
-  // `next_page_token` is empty.
+  // If `next_page_token` is not set, then all results have been returned and there is no more data
+  // to be retrieved.
   //
   // Caution: Clients must not assume a specific number of key_versions to be present in a page for
   // paginated response.

rust/api/src/kv_store_tests.rs

@@ -53,6 +53,10 @@ macro_rules! define_kv_store_tests {
 		create_test!(list_should_honour_page_size_and_key_prefix_if_provided);
 		create_test!(list_should_return_zero_global_version_when_global_versioning_not_enabled);
 		create_test!(list_should_limit_max_page_size);
+		create_test!(list_should_return_results_ordered_by_creation_time);
+		create_test!(list_should_paginate_by_creation_time_with_prefix);
+		create_test!(list_should_return_none_page_token_when_exact_fit);
+		create_test!(list_should_return_none_page_token_on_last_page);
 	};
 }
 
@@ -393,12 +397,11 @@ pub trait KvStoreTestSuite {
 				},
 			};
 
-			if current_page.key_versions.is_empty() {
-				break;
-			}
-
 			all_key_versions.extend(current_page.key_versions);
-			next_page_token = current_page.next_page_token;
+			match current_page.next_page_token {
+				Some(token) if !token.is_empty() => next_page_token = Some(token),
+				_ => break,
+			}
 		}
 
 		if let Some(k1_response) = all_key_versions.iter().find(|kv| kv.key == "k1") {
@@ -444,13 +447,12 @@ pub trait KvStoreTestSuite {
 				},
 			};
 
-			if current_page.key_versions.is_empty() {
-				break;
-			}
-
 			assert!(current_page.key_versions.len() <= page_size as usize);
 			all_key_versions.extend(current_page.key_versions);
-			next_page_token = current_page.next_page_token;
+			match current_page.next_page_token {
+				Some(token) if !token.is_empty() => next_page_token = Some(token),
+				_ => break,
+			}
 		}
 
 		let unique_keys: std::collections::HashSet<String> =
@@ -490,12 +492,11 @@ pub trait KvStoreTestSuite {
 				Some(next_page_token) => ctx.list(Some(next_page_token), None, None).await?,
 			};
 
-			if current_page.key_versions.is_empty() {
-				break;
-			}
-
 			all_key_versions.extend(current_page.key_versions);
-			next_page_token = current_page.next_page_token;
+			match current_page.next_page_token {
+				Some(token) if !token.is_empty() => next_page_token = Some(token),
+				_ => break,
+			}
 		}
 
 		let unique_keys: std::collections::HashSet<String> =
@@ -506,6 +507,93 @@ pub trait KvStoreTestSuite {
 		Ok(())
 	}
 
+	async fn list_should_return_results_ordered_by_creation_time() -> Result<(), VssError> {
+		let kv_store = Self::create_store().await;
+		let ctx = TestContext::new(&kv_store);
+
+		ctx.put_objects(None, vec![kv("z_first", "v1", 0)]).await?;
+		ctx.put_objects(None, vec![kv("a_third", "v1", 0)]).await?;
+		ctx.put_objects(None, vec![kv("m_second", "v1", 0)]).await?;
+
+		let page = ctx.list(None, None, None).await?;
+		let keys: Vec<&str> = page.key_versions.iter().map(|kv| kv.key.as_str()).collect();
+
+		// Results should be in reverse creation order (newest first), not alphabetical.
+		assert_eq!(keys, vec!["m_second", "a_third", "z_first"]);
+
+		Ok(())
+	}
+
+	async fn list_should_paginate_by_creation_time_with_prefix() -> Result<(), VssError> {
+		let kv_store = Self::create_store().await;
+		let ctx = TestContext::new(&kv_store);
+
+		// Insert prefixed keys in reverse-alphabetical order with a page_size of 1
+		// to force multiple pages and verify cross-page ordering.
+		ctx.put_objects(None, vec![kv("pfx_z", "v1", 0)]).await?;
+		ctx.put_objects(None, vec![kv("pfx_a", "v1", 0)]).await?;
+		ctx.put_objects(None, vec![kv("other", "v1", 0)]).await?;
+		ctx.put_objects(None, vec![kv("pfx_m", "v1", 0)]).await?;
+
+		let mut next_page_token: Option<String> = None;
+		let mut all_keys: Vec<String> = Vec::new();
+
+		loop {
+			let current_page = match next_page_token.take() {
+				None => ctx.list(None, Some(1), Some("pfx_".to_string())).await?,
+				Some(token) => ctx.list(Some(token), Some(1), Some("pfx_".to_string())).await?,
+			};
+
+			all_keys.extend(current_page.key_versions.into_iter().map(|kv| kv.key));
+			match current_page.next_page_token {
+				Some(token) if !token.is_empty() => next_page_token = Some(token),
+				_ => break,
+			}
+		}
+
+		// Should get prefixed keys in reverse creation order (newest first), excluding "other".
+		assert_eq!(all_keys, vec!["pfx_m", "pfx_a", "pfx_z"]);
+
+		Ok(())
+	}
+
+	async fn list_should_return_none_page_token_when_exact_fit() -> Result<(), VssError> {
+		let kv_store = Self::create_store().await;
+		let ctx = TestContext::new(&kv_store);
+
+		let page_size = 5;
+		for i in 0..page_size {
+			ctx.put_objects(None, vec![kv(&format!("k{}", i), "v1", 0)]).await?;
+		}
+
+		let page = ctx.list(None, Some(page_size), None).await?;
+		assert_eq!(page.key_versions.len(), page_size as usize);
+		assert!(page.next_page_token.is_none(), "expected None when results fit exactly in one page");
+
+		Ok(())
+	}
+
+	async fn list_should_return_none_page_token_on_last_page() -> Result<(), VssError> {
+		let kv_store = Self::create_store().await;
+		let ctx = TestContext::new(&kv_store);
+
+		let page_size = 5;
+		for i in 0..page_size + 1 {
+			ctx.put_objects(None, vec![kv(&format!("k{}", i), "v1", 0)]).await?;
+		}
+
+		let first_page = ctx.list(None, Some(page_size), None).await?;
+		assert_eq!(first_page.key_versions.len(), page_size as usize);
+		assert!(first_page.next_page_token.is_some(), "expected a page token when more items exist");
+
+		let second_page =
+			ctx.list(first_page.next_page_token, Some(page_size), None).await?;
+		assert_eq!(second_page.key_versions.len(), 1);
+		assert!(second_page.next_page_token.is_none(), "expected None on the last page");
+
+		Ok(())
+	}
+
 	async fn list_should_limit_max_page_size() -> Result<(), VssError> {
 		let kv_store = Self::create_store().await;
 		let ctx = TestContext::new(&kv_store);
@@ -524,16 +612,15 @@ pub trait KvStoreTestSuite {
 				None => ctx.list(None, None, None).await?,
 				Some(next_page_token) => ctx.list(Some(next_page_token), None, None).await?,
 			};
-			if current_page.key_versions.is_empty() {
-				break;
-			}
-
 			assert!(
 				current_page.key_versions.len() < vss_arbitrary_page_size_max as usize,
 				"Page size exceeds the maximum allowed size"
 			);
 			all_key_versions.extend(current_page.key_versions);
-			next_page_token = current_page.next_page_token;
+			match current_page.next_page_token {
+				Some(token) if !token.is_empty() => next_page_token = Some(token),
+				_ => break,
+			}
 		}
 
 		assert_eq!(all_key_versions.len(), total_kv_objects as usize);

rust/api/src/types.rs

@@ -220,12 +220,8 @@ pub struct ListKeyVersionsResponse {
 	/// Use this value to query for next-page of paginated `ListKeyVersions` operation, by specifying
 	/// this value as the `page_token` in the next request.
 	///
-	/// If `next_page_token` is empty (""), then the "last page" of results has been processed and
-	/// there is no more data to be retrieved.
-	///
-	/// If `next_page_token` is not empty, it does not necessarily mean that there is more data in the
-	/// result set. The only way to know when you have reached the end of the result set is when
-	/// `next_page_token` is empty.
+	/// If `next_page_token` is not set, then all results have been returned and there is no more data
+	/// to be retrieved.
 	///
 	/// Caution: Clients must not assume a specific number of key_versions to be present in a page for
 	/// paginated response.

rust/impls/src/migrations.rs

@@ -35,6 +35,9 @@ pub(crate) const MIGRATIONS: &[&str] = &[
 	    PRIMARY KEY (user_token, store_id, key)
 	);",
 	"ALTER TABLE vss_db DROP CONSTRAINT IF EXISTS vss_db_store_id_check;",
+	"UPDATE vss_db SET created_at = COALESCE(last_updated_at, NOW()) WHERE created_at IS NULL;",
+	"ALTER TABLE vss_db ALTER COLUMN created_at SET NOT NULL;",
+	"CREATE INDEX idx_vss_db_created_at ON vss_db (user_token, store_id, created_at, key);",
 ];
 #[cfg(test)]
 pub(crate) const DUMMY_MIGRATION: &str = "SELECT 1 WHERE FALSE;";