commit 8b3afc754910af5f77a8ff8fa0f942cc692ec59b
parent de141d793734b62c7391313c232c992d5d1ab7b5
Author: triesap <tyson@radroots.org>
Date: Sun, 11 Oct 2026 02:46:13 +0000
storage: select bounded document ranges with portable continuation
- Add exact-generation key intervals and validated after-key selection.
- Preflight payloads against caller budgets within existing maxima.
- Preserve default inventories and source/active transaction fences.
- Verify provider parity, reopen, corruption and additive public APIs.
Diffstat:
7 files changed, 580 insertions(+), 12 deletions(-)
diff --git a/contracts/api_baselines/radroots_storage.txt b/contracts/api_baselines/radroots_storage.txt
@@ -1507,6 +1507,11 @@ pub enum radroots_storage::projection::document_query::ProjectionDocumentGenerat
pub radroots_storage::projection::document_query::ProjectionDocumentGenerations::All
pub radroots_storage::projection::document_query::ProjectionDocumentGenerations::Exact(radroots_storage::projection::ProjectionGeneration)
pub struct radroots_storage::projection::document_query::ProjectionDocumentCursor
+pub struct radroots_storage::projection::document_query::ProjectionDocumentKeyRange
+impl radroots_storage::projection::document_query::ProjectionDocumentKeyRange
+pub fn radroots_storage::projection::document_query::ProjectionDocumentKeyRange::first(&self) -> &str
+pub fn radroots_storage::projection::document_query::ProjectionDocumentKeyRange::last(&self) -> &str
+pub fn radroots_storage::projection::document_query::ProjectionDocumentKeyRange::new(alloc::string::String, alloc::string::String) -> core::result::Result<Self, radroots_storage::Error>
pub struct radroots_storage::projection::document_query::ProjectionDocumentPage
impl radroots_storage::projection::document_query::ProjectionDocumentPage
pub fn radroots_storage::projection::document_query::ProjectionDocumentPage::into_records(self) -> alloc::vec::Vec<radroots_storage::projection::document_query::ProjectionDocumentRecord>
@@ -1517,11 +1522,16 @@ pub struct radroots_storage::projection::document_query::ProjectionDocumentQuery
impl radroots_storage::projection::document_query::ProjectionDocumentQuery
pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::after(&self) -> core::option::Option<(radroots_storage::projection::ProjectionGeneration, &str)>
pub const fn radroots_storage::projection::document_query::ProjectionDocumentQuery::generations(&self) -> radroots_storage::projection::document_query::ProjectionDocumentGenerations
+pub const fn radroots_storage::projection::document_query::ProjectionDocumentQuery::key_range(&self) -> core::option::Option<&radroots_storage::projection::document_query::ProjectionDocumentKeyRange>
pub const fn radroots_storage::projection::document_query::ProjectionDocumentQuery::limit(&self) -> u16
pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::matches(&self, radroots_storage::projection::ProjectionGeneration, &str) -> bool
pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::new(radroots_storage::projection::ProjectionId, radroots_storage::projection::document_query::ProjectionDocumentGenerations, u16) -> core::result::Result<Self, radroots_storage::Error>
+pub const fn radroots_storage::projection::document_query::ProjectionDocumentQuery::payload_budget(&self) -> usize
pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::projection_id(&self) -> &radroots_storage::projection::ProjectionId
+pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::with_after_key(self, alloc::string::String) -> core::result::Result<Self, radroots_storage::Error>
pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::with_cursor(self, &radroots_storage::projection::document_query::ProjectionDocumentCursor) -> core::result::Result<Self, radroots_storage::Error>
+pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::with_key_range(self, radroots_storage::projection::document_query::ProjectionDocumentKeyRange) -> core::result::Result<Self, radroots_storage::Error>
+pub fn radroots_storage::projection::document_query::ProjectionDocumentQuery::with_payload_budget(self, usize) -> core::result::Result<Self, radroots_storage::Error>
pub struct radroots_storage::projection::document_query::ProjectionDocumentRecord
impl radroots_storage::projection::document_query::ProjectionDocumentRecord
pub fn radroots_storage::projection::document_query::ProjectionDocumentRecord::corrupt(radroots_storage::projection::ProjectionGeneration, alloc::string::String) -> core::result::Result<Self, radroots_storage::Error>
diff --git a/contracts/architecture/decisions/projection_document_inventory.v2.json b/contracts/architecture/decisions/projection_document_inventory.v2.json
@@ -0,0 +1,13 @@
+{
+ "schema": "radroots.projection-document-inventory.v2",
+ "status": "implemented_candidate",
+ "supersedes_without_mutation": "radroots.projection-document-inventory.v1",
+ "owners": ["radroots_storage", "radroots_storage_sqlite"],
+ "selection": "Optional validated inclusive UTF-8 key intervals select one exact generation. Independently supplied identity, generation and interval bind provider-produced continuations. A validated after-key can seek within that exact selection without creating a retained session. Neither mechanism establishes frozen application scope or proves position existence.",
+ "bounds": {"page_records": 256, "metadata_lookahead": 1, "key_bytes": 512, "generation_bytes": 32, "digest_bytes": 32, "maximum_page_payload_bytes": 16777216, "minimum_caller_payload_budget": 1},
+ "allocation": "A caller may lower the encoded payload budget within the existing maximum. Providers inspect scalar lengths before cloning or loading payloads. A first valid value that cannot fit returns SpaceInsufficient; exhaustion after admitted records returns a continuation. Metadata remains separately bounded by count plus one lookahead. Callers charge decoding, intermediate buffers and product work within their own envelope.",
+ "consistency": "Key ranges use bounded BTreeMap selection or SQLite primary-key predicates. Source-bound reads retain the exact canonical source, Ready health, registered promoted generation and expected-active checks under the same existing transaction or lock.",
+ "corruption": "Keep explicit bounded corrupt-record locators for invalid stored values; invalid key/generation prevents safe continuation. No malformed record or oversized valid value becomes empty complete success.",
+ "compatibility": "Default queries preserve the original full inventory, ordering, byte maximum and corruption rules. Historical v1 contract, stored bytes, migrations, features, dependencies and unsupported-provider refusals remain unchanged.",
+ "non_goals": ["application ranking or schema", "frozen product cursors", "new snapshots or leases", "garbage collection policy", "raw SQL escape hatch", "new database", "release qualification"]
+}
diff --git a/crates/storage/src/memory_projection_batch.rs b/crates/storage/src/memory_projection_batch.rs
@@ -6,8 +6,8 @@ use crate::{
ProjectionId, ProjectionStatus,
batch::{ProjectionDocumentBatch, ProjectionWriteScope},
document_query::{
- PROJECTION_DOCUMENT_PAGE_BYTES_MAX, ProjectionDocumentGenerations,
- ProjectionDocumentPage, ProjectionDocumentQuery, ProjectionDocumentRecord,
+ ProjectionDocumentGenerations, ProjectionDocumentPage, ProjectionDocumentQuery,
+ ProjectionDocumentRecord,
},
},
};
@@ -206,12 +206,23 @@ pub(super) fn page(
};
// The smallest valid generation is [0,..,1]; zero is never admitted.
let start = query.after().map_or_else(
- || Included((id.clone(), generation, String::new())),
+ || {
+ Included((
+ id.clone(),
+ generation,
+ query
+ .key_range()
+ .map_or_else(String::new, |range| range.first().to_owned()),
+ ))
+ },
|(generation, key)| Excluded((id.clone(), generation, key.to_owned())),
);
+ let end = query.key_range().map_or(Unbounded, |range| {
+ Included((id.clone(), generation, range.last().to_owned()))
+ });
let selected: Vec<_> = state
.projection_documents
- .range((start, Unbounded))
+ .range((start, end))
.take_while(|((row_id, generation, _), _)| {
row_id == &id
&& match query.generations() {
@@ -225,7 +236,10 @@ pub(super) fn page(
let mut records = Vec::new();
let mut bytes = 0usize;
for ((_, generation, _), document) in selected.into_iter().take(usize::from(query.limit())) {
- if bytes + document.value().len() > PROJECTION_DOCUMENT_PAGE_BYTES_MAX {
+ if bytes + document.value().len() > query.payload_budget() {
+ if records.is_empty() {
+ return Err(Error::SpaceInsufficient);
+ }
more = true;
break;
}
diff --git a/crates/storage/src/projection/document_query.rs b/crates/storage/src/projection/document_query.rs
@@ -1,11 +1,38 @@
//! Bounded opaque document inventory. A continuation is not a frozen snapshot.
#[cfg(test)]
+mod selection_tests;
+#[cfg(test)]
mod tests;
use super::{Error, ProjectionDocument, ProjectionGeneration, ProjectionId, valid_document_key};
pub const PROJECTION_DOCUMENT_QUERY_LIMIT_MAX: u16 = 256;
pub const PROJECTION_DOCUMENT_PAGE_BYTES_MAX: usize = super::PROJECTION_DOCUMENT_VALUE_MAX_BYTES;
+/// Inclusive opaque key interval within one independently selected generation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ProjectionDocumentKeyRange {
+ first: String,
+ last: String,
+}
+
+impl ProjectionDocumentKeyRange {
+ pub fn new(first: String, last: String) -> Result<Self, Error> {
+ if !valid_document_key(&first) || !valid_document_key(&last) || first > last {
+ return Err(Error::InvalidProjectionDocument);
+ }
+ Ok(Self { first, last })
+ }
+ pub fn first(&self) -> &str {
+ &self.first
+ }
+ pub fn last(&self) -> &str {
+ &self.last
+ }
+ fn contains(&self, key: &str) -> bool {
+ self.first.as_str() <= key && key <= self.last.as_str()
+ }
+}
+
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProjectionDocumentGenerations {
Exact(ProjectionGeneration),
@@ -18,6 +45,8 @@ pub struct ProjectionDocumentQuery {
generations: ProjectionDocumentGenerations,
limit: u16,
after: Option<(ProjectionGeneration, String)>,
+ key_range: Option<ProjectionDocumentKeyRange>,
+ payload_budget: usize,
}
impl ProjectionDocumentQuery {
@@ -38,15 +67,62 @@ impl ProjectionDocumentQuery {
generations,
limit,
after: None,
+ key_range: None,
+ payload_budget: PROJECTION_DOCUMENT_PAGE_BYTES_MAX,
})
}
pub fn with_cursor(mut self, cursor: &ProjectionDocumentCursor) -> Result<Self, Error> {
- if self.projection_id != cursor.projection_id || self.generations != cursor.generations {
+ if self.projection_id != cursor.projection_id
+ || self.generations != cursor.generations
+ || self.key_range != cursor.key_range
+ {
return Err(Error::InvalidProjectionDocument);
}
self.after = Some(cursor.after.clone());
Ok(self)
}
+ /// Configure selection before seeking; a continuation cannot widen this interval.
+ pub fn with_key_range(mut self, range: ProjectionDocumentKeyRange) -> Result<Self, Error> {
+ if !matches!(self.generations, ProjectionDocumentGenerations::Exact(_))
+ || self.after.is_some()
+ {
+ return Err(Error::InvalidProjectionDocument);
+ }
+ self.key_range = Some(range);
+ Ok(self)
+ }
+ /// Seek a caller-validated key in this exact generation, without a retained snapshot.
+ /// This does not prove that the position exists or freeze application read scope.
+ pub fn with_after_key(mut self, key: String) -> Result<Self, Error> {
+ let ProjectionDocumentGenerations::Exact(generation) = self.generations else {
+ return Err(Error::InvalidProjectionDocument);
+ };
+ if !valid_document_key(&key)
+ || self
+ .key_range
+ .as_ref()
+ .is_some_and(|range| !range.contains(&key))
+ {
+ return Err(Error::InvalidProjectionDocument);
+ }
+ self.after = Some((generation, key));
+ Ok(self)
+ }
+ /// Lower the encoded-payload ceiling before provider allocation. Metadata remains
+ /// bounded by the record limit plus one lookahead; callers charge their decoding.
+ pub fn with_payload_budget(mut self, bytes: usize) -> Result<Self, Error> {
+ if bytes == 0 || bytes > PROJECTION_DOCUMENT_PAGE_BYTES_MAX {
+ return Err(Error::InvalidProjectionDocument);
+ }
+ self.payload_budget = bytes;
+ Ok(self)
+ }
+ pub const fn payload_budget(&self) -> usize {
+ self.payload_budget
+ }
+ pub const fn key_range(&self) -> Option<&ProjectionDocumentKeyRange> {
+ self.key_range.as_ref()
+ }
pub fn projection_id(&self) -> &ProjectionId {
&self.projection_id
}
@@ -66,6 +142,10 @@ impl ProjectionDocumentQuery {
ProjectionDocumentGenerations::Exact(expected) => generation == expected,
ProjectionDocumentGenerations::All => true,
}) && self.after().is_none_or(|after| (generation, key) > after)
+ && self
+ .key_range
+ .as_ref()
+ .is_none_or(|range| range.contains(key))
}
}
@@ -75,6 +155,7 @@ pub struct ProjectionDocumentCursor {
projection_id: ProjectionId,
generations: ProjectionDocumentGenerations,
after: (ProjectionGeneration, String),
+ key_range: Option<ProjectionDocumentKeyRange>,
}
/// An absent document is explicit corruption requiring caller reconciliation.
@@ -155,7 +236,7 @@ impl ProjectionDocumentPage {
bytes += record
.document()
.map_or(0, |document| document.value().len());
- if bytes > PROJECTION_DOCUMENT_PAGE_BYTES_MAX {
+ if bytes > query.payload_budget {
return Err(Error::InvalidProjectionDocument);
}
previous = Some(position);
@@ -165,6 +246,7 @@ impl ProjectionDocumentPage {
projection_id: query.projection_id.clone(),
generations: query.generations,
after: (generation, key.to_owned()),
+ key_range: query.key_range.clone(),
})
} else {
None
diff --git a/crates/storage/src/projection/document_query/selection_tests.rs b/crates/storage/src/projection/document_query/selection_tests.rs
@@ -0,0 +1,109 @@
+use super::*;
+
+fn generation(byte: u8) -> ProjectionGeneration {
+ ProjectionGeneration::new([byte; 32]).unwrap()
+}
+fn query() -> ProjectionDocumentQuery {
+ ProjectionDocumentQuery::new(
+ ProjectionId::parse("fixture").unwrap(),
+ ProjectionDocumentGenerations::Exact(generation(1)),
+ 2,
+ )
+ .unwrap()
+}
+fn range(first: &str, last: &str) -> ProjectionDocumentKeyRange {
+ ProjectionDocumentKeyRange::new(first.into(), last.into()).unwrap()
+}
+fn record(key: &str, bytes: usize) -> ProjectionDocumentRecord {
+ ProjectionDocumentRecord::new(
+ generation(1),
+ ProjectionDocument::new(key.into(), vec![1; bytes]).unwrap(),
+ )
+ .unwrap()
+}
+
+#[test]
+fn selection_validates_key_and_payload_boundaries_before_provider_work() {
+ for key in ["", " bad", "bad\n", &"x".repeat(513), &"é".repeat(257)] {
+ assert!(ProjectionDocumentKeyRange::new(key.into(), key.into()).is_err());
+ assert!(query().with_after_key(key.into()).is_err());
+ }
+ let maximum = "é".repeat(256);
+ assert_eq!(range(&maximum, &maximum).first().len(), 512);
+ assert!(query().with_after_key(maximum).is_ok());
+ assert!(ProjectionDocumentKeyRange::new("z".into(), "a".into()).is_err());
+ for bytes in [0, PROJECTION_DOCUMENT_PAGE_BYTES_MAX + 1, usize::MAX] {
+ assert!(query().with_payload_budget(bytes).is_err());
+ }
+ for bytes in [1, PROJECTION_DOCUMENT_PAGE_BYTES_MAX] {
+ assert_eq!(
+ query().with_payload_budget(bytes).unwrap().payload_budget(),
+ bytes
+ );
+ }
+ let all = ProjectionDocumentQuery::new(
+ query().projection_id().clone(),
+ ProjectionDocumentGenerations::All,
+ 1,
+ )
+ .unwrap();
+ assert!(all.clone().with_key_range(range("a", "z")).is_err());
+ assert!(all.with_after_key("a".into()).is_err());
+ for key in ["a", "z"] {
+ assert!(
+ query()
+ .with_key_range(range("b", "y"))
+ .unwrap()
+ .with_after_key(key.into())
+ .is_err()
+ );
+ }
+ assert!(
+ query()
+ .with_after_key("c".into())
+ .unwrap()
+ .with_key_range(range("a", "z"))
+ .is_err()
+ );
+}
+
+#[test]
+fn selected_continuations_cannot_widen_range_or_cross_generation() {
+ let selected = query().with_key_range(range("b", "é")).unwrap();
+ let page =
+ ProjectionDocumentPage::new(&selected, vec![record("b", 1), record("z", 1)], true).unwrap();
+ let cursor = page.next_cursor().unwrap();
+ let resumed = selected.clone().with_cursor(cursor).unwrap();
+ let sought = selected.clone().with_after_key("z".into()).unwrap();
+ assert_eq!(resumed, sought);
+ assert!(ProjectionDocumentPage::new(&sought, vec![record("é", 1)], false).is_ok());
+ for changed in [
+ query(),
+ query().with_key_range(range("a", "é")).unwrap(),
+ ProjectionDocumentQuery::new(
+ query().projection_id().clone(),
+ ProjectionDocumentGenerations::Exact(generation(2)),
+ 2,
+ )
+ .unwrap()
+ .with_key_range(range("b", "é"))
+ .unwrap(),
+ ] {
+ assert!(changed.with_cursor(cursor).is_err());
+ }
+ for key in ["a", "ê"] {
+ assert!(ProjectionDocumentPage::new(&selected, vec![record(key, 1)], false).is_err());
+ }
+ let exact = query().with_key_range(range("é", "é")).unwrap();
+ assert_eq!(
+ ProjectionDocumentPage::new(&exact, vec![record("é", 1)], false)
+ .unwrap()
+ .records()
+ .len(),
+ 1
+ );
+ let budget = selected.with_payload_budget(7).unwrap();
+ assert!(
+ ProjectionDocumentPage::new(&budget, vec![record("b", 4), record("c", 4)], false).is_err()
+ );
+}
diff --git a/crates/storage_sqlite/src/projection/document_query.rs b/crates/storage_sqlite/src/projection/document_query.rs
@@ -56,10 +56,7 @@ pub(super) async fn page_at(
}
}
-async fn read_page(
- transaction: &mut sqlx::Transaction<'_, sqlx::Sqlite>,
- query: &ProjectionDocumentQuery,
-) -> Result<ProjectionDocumentPage, Error> {
+fn selection(query: &ProjectionDocumentQuery) -> sqlx::QueryBuilder<sqlx::Sqlite> {
// CASE bounds every variable-width metadata value before SQLx allocates it.
// Payloads are loaded separately, only after charging this page's byte budget.
let mut selection = sqlx::QueryBuilder::new(
@@ -84,9 +81,24 @@ async fn read_page(
.push_bind(key)
.push(")");
}
+ if let Some(range) = query.key_range() {
+ selection
+ .push(" AND document_key >= ")
+ .push_bind(range.first())
+ .push(" AND document_key <= ")
+ .push_bind(range.last());
+ }
selection
.push(" ORDER BY documents.generation, documents.document_key LIMIT ")
.push_bind(i64::from(query.limit()) + 1);
+ selection
+}
+
+async fn read_page(
+ transaction: &mut sqlx::Transaction<'_, sqlx::Sqlite>,
+ query: &ProjectionDocumentQuery,
+) -> Result<ProjectionDocumentPage, Error> {
+ let mut selection = selection(query);
let rows = selection
.build()
.fetch_all(&mut **transaction)
@@ -127,7 +139,10 @@ async fn read_page(
continue;
}
let size = size as usize;
- if bytes + size > PROJECTION_DOCUMENT_PAGE_BYTES_MAX {
+ if bytes + size > query.payload_budget() {
+ if records.is_empty() {
+ return Err(Error::SpaceInsufficient);
+ }
has_more = true;
break;
}
@@ -147,4 +162,6 @@ async fn read_page(
}
#[cfg(test)]
+mod selection_tests;
+#[cfg(test)]
mod tests;
diff --git a/crates/storage_sqlite/src/projection/document_query/selection_tests.rs b/crates/storage_sqlite/src/projection/document_query/selection_tests.rs
@@ -0,0 +1,323 @@
+use super::*;
+use crate::{OpenMode, OpenOptions, Paths};
+use radroots_storage::{
+ ProjectionStore,
+ event::{EventSourceToken, SourceGeneration},
+ memory::MemoryStorage,
+ projection::{
+ InvalidationReason, ProjectionCheckpoint, ProjectionId, ProjectionInvalidation,
+ batch::{ProjectionDocumentBatch, ProjectionWriteScope},
+ document_query::ProjectionDocumentKeyRange,
+ },
+};
+use sqlx::Execute;
+use tempfile::TempDir;
+
+fn id() -> ProjectionId {
+ ProjectionId::parse("fixture").unwrap()
+}
+fn generation(byte: u8) -> ProjectionGeneration {
+ ProjectionGeneration::new([byte; 32]).unwrap()
+}
+fn range(first: &str, last: &str) -> ProjectionDocumentKeyRange {
+ ProjectionDocumentKeyRange::new(first.into(), last.into()).unwrap()
+}
+fn query(limit: u16) -> ProjectionDocumentQuery {
+ ProjectionDocumentQuery::new(
+ id(),
+ ProjectionDocumentGenerations::Exact(generation(1)),
+ limit,
+ )
+ .unwrap()
+}
+async fn open(temp: &TempDir) -> SqliteStorage {
+ SqliteStorage::open(
+ OpenOptions::new(
+ Paths::from_directory(temp.path()).unwrap(),
+ OpenMode::Create,
+ )
+ .with_source_generation(SourceGeneration::new([9; 32]).unwrap(), 9)
+ .unwrap(),
+ )
+ .await
+ .unwrap()
+}
+async fn promote(store: &dyn radroots_storage::Storage) -> EventSourceToken {
+ let source = store.source_token().await.unwrap();
+ let scope = ProjectionWriteScope::new(id(), generation(1), source, None).unwrap();
+ let documents: Vec<_> = ["a", "m", "z"]
+ .into_iter()
+ .flat_map(|prefix| {
+ (0..100).map(move |number| {
+ ProjectionDocument::new(format!("{prefix}.{number:04}"), vec![1; 4]).unwrap()
+ })
+ })
+ .collect();
+ for chunk in documents.chunks(64) {
+ store
+ .put_projection_batch(
+ ProjectionDocumentBatch::new(scope.clone(), chunk.to_vec()).unwrap(),
+ )
+ .await
+ .unwrap();
+ }
+ store
+ .promote_projection_batch(
+ ProjectionDocumentBatch::new(
+ scope,
+ vec![ProjectionDocument::new("zz.end".into(), vec![1]).unwrap()],
+ )
+ .unwrap(),
+ ProjectionCheckpoint::new(id(), generation(1), None, 301, 9).unwrap(),
+ )
+ .await
+ .unwrap();
+ source
+}
+
+#[tokio::test]
+async fn selected_primary_key_pages_match_memory_and_portable_seek_after_reopen() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ let source = promote(&store).await;
+ assert_eq!(promote(&memory).await, source);
+ let q = query(17)
+ .with_key_range(range("m.0003", "m.0098"))
+ .unwrap()
+ .with_payload_budget(68)
+ .unwrap();
+ let mut selected = q.clone();
+ let mut found = Vec::new();
+ loop {
+ let page = store
+ .query_projection_documents_at(selected.clone(), source, generation(1))
+ .await
+ .unwrap();
+ assert_eq!(
+ page,
+ memory
+ .query_projection_documents_at(selected.clone(), source, generation(1))
+ .await
+ .unwrap()
+ );
+ assert!(page.records().len() <= 17);
+ assert!(
+ page.records()
+ .iter()
+ .map(|row| row.document().unwrap().value().len())
+ .sum::<usize>()
+ <= 68
+ );
+ found.extend(page.records().iter().map(|row| row.key().to_owned()));
+ let Some(cursor) = page.next_cursor() else {
+ break;
+ };
+ selected = q.clone().with_cursor(cursor).unwrap();
+ assert_eq!(
+ selected,
+ q.clone()
+ .with_after_key(found.last().unwrap().clone())
+ .unwrap()
+ );
+ }
+ assert_eq!(
+ found,
+ (3..=98)
+ .map(|number| format!("m.{number:04}"))
+ .collect::<Vec<_>>()
+ );
+ let resume = q.clone().with_after_key("m.0050".into()).unwrap();
+ let expected = memory
+ .query_projection_documents_at(resume.clone(), source, generation(1))
+ .await
+ .unwrap();
+ store.close().await.unwrap();
+ let store = SqliteStorage::open(OpenOptions::new(
+ Paths::from_directory(temp.path()).unwrap(),
+ OpenMode::ReadOnly,
+ ))
+ .await
+ .unwrap();
+ assert_eq!(
+ store
+ .query_projection_documents_at(resume, source, generation(1))
+ .await
+ .unwrap(),
+ expected
+ );
+ assert!(
+ store
+ .query_projection_documents_at(
+ q.with_after_key("m.0098".into()).unwrap(),
+ source,
+ generation(1)
+ )
+ .await
+ .unwrap()
+ .records()
+ .is_empty()
+ );
+ let mut builder = selection(&selected);
+ let mut actual = builder.build();
+ let arguments = actual.take_arguments().unwrap().unwrap();
+ let explanation = format!("EXPLAIN QUERY PLAN {}", actual.sql().as_ref());
+ // Only a constant prefix decorates the actual bound-value selection SQL.
+ let mut explanation =
+ sqlx::QueryBuilder::<sqlx::Sqlite>::with_arguments(explanation, arguments);
+ let rows = explanation.build().fetch_all(store.pool()).await.unwrap();
+ let details: Vec<String> = rows.iter().map(|row| row.get("detail")).collect();
+ assert!(
+ details.iter().any(|value| value.contains("PRIMARY KEY")
+ && value.contains("document_key>")
+ && value.contains("document_key<")),
+ "{details:?}"
+ );
+ assert!(
+ !details.iter().any(|value| value.starts_with("SCAN ")),
+ "{details:?}"
+ );
+ store.close().await.unwrap();
+}
+
+#[tokio::test]
+async fn lower_payload_budget_preflights_valid_values_and_preserves_corruption() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ for backend in [&store as &dyn ProjectionStore, &memory] {
+ for (key, bytes) in [("a", 4), ("b", 6)] {
+ backend
+ .put_projection_document(
+ id(),
+ generation(1),
+ ProjectionDocument::new(key.into(), vec![7; bytes]).unwrap(),
+ )
+ .await
+ .unwrap();
+ }
+ let q = query(2).with_payload_budget(4).unwrap();
+ let first = backend.query_projection_documents(q.clone()).await.unwrap();
+ assert_eq!(first.records().len(), 1);
+ assert_eq!(first.records()[0].key(), "a");
+ assert_eq!(
+ backend
+ .query_projection_documents(q.with_cursor(first.next_cursor().unwrap()).unwrap())
+ .await,
+ Err(Error::SpaceInsufficient)
+ );
+ assert_eq!(
+ backend
+ .query_projection_documents(
+ query(1)
+ .with_key_range(range("a", "a"))
+ .unwrap()
+ .with_payload_budget(3)
+ .unwrap()
+ )
+ .await,
+ Err(Error::SpaceInsufficient)
+ );
+ let exact = backend
+ .query_projection_documents(
+ query(1)
+ .with_key_range(range("b", "b"))
+ .unwrap()
+ .with_payload_budget(6)
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(exact.records()[0].document().unwrap().value(), &[7; 6]);
+ assert!(exact.next_cursor().is_none());
+ assert_eq!(
+ backend
+ .projection_document(id(), generation(1), "a".into())
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ &[7; 4]
+ );
+ }
+ sqlx::query("UPDATE radroots_runtime_projection_documents SET value_sha256=zeroblob(32) WHERE document_key='b'").execute(store.pool()).await.unwrap();
+ let b = query(1).with_key_range(range("b", "b")).unwrap();
+ assert_eq!(
+ store
+ .query_projection_documents(b.clone().with_payload_budget(4).unwrap())
+ .await,
+ Err(Error::SpaceInsufficient)
+ );
+ assert!(
+ store
+ .query_projection_documents(b.with_payload_budget(6).unwrap())
+ .await
+ .unwrap()
+ .records()[0]
+ .document()
+ .is_none()
+ );
+ store.close().await.unwrap();
+}
+
+#[tokio::test]
+async fn key_selection_retains_source_active_and_ready_transaction_fences() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ for backend in [&store as &dyn radroots_storage::Storage, &memory] {
+ let source = promote(backend).await;
+ let q = query(1).with_key_range(range("m.0000", "m.0000")).unwrap();
+ assert_eq!(
+ backend
+ .query_projection_documents_at(q.clone(), source, generation(1))
+ .await
+ .unwrap()
+ .records()[0]
+ .key(),
+ "m.0000"
+ );
+ let foreign = EventSourceToken::new(SourceGeneration::new([8; 32]).unwrap(), 0);
+ assert_eq!(
+ backend
+ .query_projection_documents_at(q.clone(), foreign, generation(1))
+ .await,
+ Err(Error::SourceEpochChanged)
+ );
+ assert_eq!(
+ backend
+ .query_projection_documents_at(q.clone(), source, generation(2))
+ .await,
+ Err(Error::InvalidProjectionDocument)
+ );
+ backend
+ .invalidate(
+ ProjectionInvalidation::new(
+ id(),
+ generation(1),
+ generation(2),
+ InvalidationReason::ProjectionGenerationChanged,
+ 10,
+ )
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ backend
+ .query_projection_documents_at(q, source, generation(1))
+ .await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ backend
+ .projection_document(id(), generation(1), "m.0000".into())
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ &[1; 4]
+ );
+ }
+ store.close().await.unwrap();
+}