lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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:
Mcontracts/api_baselines/radroots_storage.txt | 10++++++++++
Acontracts/architecture/decisions/projection_document_inventory.v2.json | 13+++++++++++++
Mcrates/storage/src/memory_projection_batch.rs | 24+++++++++++++++++++-----
Mcrates/storage/src/projection/document_query.rs | 86+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
Acrates/storage/src/projection/document_query/selection_tests.rs | 109+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcrates/storage_sqlite/src/projection/document_query.rs | 27++++++++++++++++++++++-----
Acrates/storage_sqlite/src/projection/document_query/selection_tests.rs | 323+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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(); +}