commit de141d793734b62c7391313c232c992d5d1ab7b5
parent 65410d47c90160ab45c91b185101fdcf6cdf7e12
Author: triesap <tyson@radroots.org>
Date: Sun, 11 Oct 2026 00:56:31 +0000
storage: preserve refusal while retiring legacy coordination
- Extend exact retirement to invalidated inactive legacy checkpoints.
- Preserve source fences, refusal status and all retained document bytes.
- Keep cache registration, collection authority and capacity limits unchanged.
- Verify provider parity, durable reopen and rebuild/batch refusals.
Diffstat:
5 files changed, 458 insertions(+), 16 deletions(-)
diff --git a/contracts/architecture/decisions/projection_cache_retirement.v2.json b/contracts/architecture/decisions/projection_cache_retirement.v2.json
@@ -0,0 +1,29 @@
+{
+ "schema": "radroots.projection-cache-retirement.v2",
+ "status": "implemented_candidate",
+ "owners": [
+ "radroots_storage",
+ "radroots_storage_sqlite"
+ ],
+ "authority": "Explicit cache identity registration and immutable positive caller-owned limits. Application policy remains outside Lib. Unsupported providers refuse the new methods.",
+ "accounting": "One store-wide logical value-byte, protected-generation and legacy-snapshot budget includes legacy, active and staging projection rows. Scalar migration initialization is explicit; subsequent declared writers update cached counters under their owner lock or transaction. Growing admission refuses capacity without partial rows or status. Collection may reduce pre-existing excess.",
+ "retirement": "Exact registered cache owner, canonical source token and expected active generation are compared before effects. A current Ready active generation is protected. Obsolete, staged or explicitly invalidated generations can be retired. Stale active retirement clears its derived status atomically; canonical events, authored work, intents, receipts and media custody are untouched. An exact unconfigured legacy checkpoint may release metadata protection only when explicitly Invalidated, without an active rebuild or live batch registration, under the complete canonical source token and expected-active fence. Its checkpoint source generation must match the canonical store. Preserve Invalidated status and all document/snapshot bytes. Exact repeated retirement is idempotent and grants no cache-owner registration or collection authority.",
+ "collection": "At most64 total exact-generation document, legacy snapshot and registration rows per pass. Active/staging documents are protected. Unrelated projection identities cannot be collected unless explicitly registered as derived cache by their owner. Continuation reflects remaining eligible work. Metadata selection and deletion occur in one transaction or lock, without payload hydration.",
+ "legacy_snapshots": "Configured cache identities create no new whole-view snapshot sessions. Existing exact duplicate replay cannot extend fixed expiry. Owner wall time and a durable high-water govern legacy expiry; caller as-of is never a clock input. Configured legacy snapshot reads on a read-only provider refuse continuation. Exact unconfigured lookups validate scalar lengths and fixed digests before hydration.",
+ "compatibility": "Historical migrations1-21 are immutable. Forward22 owns only derived-cache accounting, registration and indexes. Unconfigured inventory semantics remain supported. Physical database/WAL pages are separate from logical live value-byte quota and are not promised to shrink after collection.",
+ "non_goals": [
+ "leases",
+ "new per-read snapshots",
+ "application policy",
+ "canonical data deletion",
+ "new database",
+ "worker",
+ "vacuum",
+ "physical-device qualification"
+ ],
+ "batch_admission": "One final aggregate policy independent of input order. Up to64 scalar old lengths are preflighted in BEGIN IMMEDIATE. True aggregate growth beyond immutable configured limits refuses before payload effects; non-growing replacement can reduce pre-existing excess. A private final-byte reservation exists only inside that transaction, shrinking rows precede growth, and exact counters/reservation are checked and cleared before commit. Failure, cancellation and crash roll back the transaction. Direct writers retain ordinary per-write guards. Historical migrations1-21 remain unchanged.",
+ "supersedes_without_mutation": {
+ "path": "contracts/architecture/decisions/projection_cache_retirement.v1.json",
+ "sha256": "166ff761aea04d96517398e76803e290e81ae07eb3598ae3f2774d0f6dc6c6b4"
+ }
+}
diff --git a/crates/storage/src/memory_projection_cache.rs b/crates/storage/src/memory_projection_cache.rs
@@ -111,16 +111,12 @@ fn fence(
if scope.source() != EventSourceToken::new(generation, state.event_mutation_epoch) {
return Err(Error::SourceEpochChanged);
}
- if !state
- .projection_cache
- .owners
- .contains(scope.projection_id())
- || state
- .projections
- .iter()
- .find(|value| value.projection_id() == scope.projection_id())
- .map(|value| value.generation())
- != scope.expected_active()
+ if state
+ .projections
+ .iter()
+ .find(|value| value.projection_id() == scope.projection_id())
+ .map(|value| value.generation())
+ != scope.expected_active()
{
return Err(Error::ProjectionRevisionConflict);
}
@@ -134,6 +130,29 @@ pub(super) fn retire(
fence(state, source, &scope)?;
let identity = (scope.projection_id().clone(), scope.generation());
let prior = state.projection_generations.get(&identity);
+ let configured = state
+ .projection_cache
+ .owners
+ .contains(scope.projection_id());
+ if !configured {
+ let legacy = state
+ .projections
+ .iter()
+ .find(|value| value.projection_id() == scope.projection_id());
+ if scope.expected_active() != Some(scope.generation())
+ || legacy.is_none_or(|value| {
+ value.health() != ProjectionHealth::Invalidated
+ || value.active_rebuild().is_some()
+ || value
+ .checkpoint()
+ .and_then(|value| value.source_position())
+ .is_some_and(|position| position.generation() != source)
+ })
+ || prior.is_some_and(|value| value.phase != projection_batch::Phase::Retired)
+ {
+ return Err(Error::ProjectionRevisionConflict);
+ }
+ }
if scope.expected_active() == Some(scope.generation()) {
let current = state
.projections
@@ -165,7 +184,7 @@ pub(super) fn retire(
},
);
state.projection_cache.protected.remove(&identity);
- if scope.expected_active() == Some(scope.generation()) {
+ if configured && scope.expected_active() == Some(scope.generation()) {
state
.projections
.retain(|value| value.projection_id() != scope.projection_id());
@@ -179,6 +198,13 @@ pub(super) fn collect(
now: u64,
) -> Result<ProjectionCacheCollection, Error> {
fence(state, source, &scope)?;
+ if !state
+ .projection_cache
+ .owners
+ .contains(scope.projection_id())
+ {
+ return Err(Error::ProjectionRevisionConflict);
+ }
let identity = (scope.projection_id().clone(), scope.generation());
let reserved = state
.projection_generations
diff --git a/crates/storage/src/projection.rs b/crates/storage/src/projection.rs
@@ -1039,6 +1039,9 @@ pub trait ProjectionStore: Send + Sync {
Box::pin(async { Err(Error::BackendUnavailable) })
}
/// Retires an exact obsolete generation without touching canonical or authored data.
+ /// An unconfigured legacy checkpoint must be explicitly invalidated without an
+ /// active rebuild; retirement retains its refusal status and bytes, and grants
+ /// no collection authority. Source and expected-active fences still apply.
fn retire_projection_generation(
&self,
_scope: cache::ProjectionCacheScope,
diff --git a/crates/storage_sqlite/src/projection/cache.rs b/crates/storage_sqlite/src/projection/cache.rs
@@ -124,9 +124,7 @@ async fn fence(
.as_ref()
.map(decode_status)
.transpose()?;
- if !owner(transaction, scope.projection_id()).await?
- || status.as_ref().map(|value| value.generation()) != scope.expected_active()
- {
+ if status.as_ref().map(|value| value.generation()) != scope.expected_active() {
return Err(Error::ProjectionRevisionConflict);
}
Ok(status)
@@ -142,7 +140,27 @@ pub(super) async fn retire(
.await
.map_err(map)?;
let status = fence(&mut transaction, store, &scope).await?;
- let row = sqlx::query("SELECT source_generation,source_epoch FROM radroots_runtime_projection_generations WHERE projection_id=? AND generation=?").bind(scope.projection_id().as_str()).bind(scope.generation().as_bytes().as_slice()).fetch_optional(&mut *transaction).await.map_err(map)?;
+ let row = sqlx::query("SELECT source_generation,source_epoch,phase FROM radroots_runtime_projection_generations WHERE projection_id=? AND generation=?").bind(scope.projection_id().as_str()).bind(scope.generation().as_bytes().as_slice()).fetch_optional(&mut *transaction).await.map_err(map)?;
+ let configured = owner(&mut transaction, scope.projection_id()).await?;
+ if !configured {
+ let phase = row
+ .as_ref()
+ .map(|row| row.try_get::<String, _>("phase").map_err(map_corrupt))
+ .transpose()?;
+ if scope.expected_active() != Some(scope.generation())
+ || status.as_ref().is_none_or(|value| {
+ value.health() != ProjectionHealth::Invalidated
+ || value.active_rebuild().is_some()
+ || value
+ .checkpoint()
+ .and_then(|value| value.source_position())
+ .is_some_and(|position| position.generation() != store.generation)
+ })
+ || phase.as_deref().is_some_and(|value| value != "retired")
+ {
+ return Err(Error::ProjectionRevisionConflict);
+ }
+ }
if scope.expected_active() == Some(scope.generation())
&& status
.as_ref()
@@ -162,7 +180,7 @@ pub(super) async fn retire(
}
sqlx::query("INSERT INTO radroots_runtime_projection_generations(projection_id,generation,source_generation,source_epoch,expected_active,phase) VALUES(?,?,?,?,NULL,'retired') ON CONFLICT(projection_id,generation) DO UPDATE SET phase='retired'")
.bind(scope.projection_id().as_str()).bind(scope.generation().as_bytes().as_slice()).bind(scope.source().generation().as_bytes().as_slice()).bind(i64_from_u64(scope.source().epoch())?).execute(&mut *transaction).await.map_err(map)?;
- if scope.expected_active() == Some(scope.generation()) {
+ if configured && scope.expected_active() == Some(scope.generation()) {
sqlx::query("DELETE FROM radroots_runtime_projection_checkpoints WHERE projection_id=? AND projection_generation=?").bind(scope.projection_id().as_str()).bind(scope.generation().as_bytes().as_slice()).execute(&mut *transaction).await.map_err(map)?;
}
let current = usage(&mut transaction).await?;
@@ -180,6 +198,9 @@ pub(super) async fn collect(
.await
.map_err(map)?;
fence(&mut transaction, store, &scope).await?;
+ if !owner(&mut transaction, scope.projection_id()).await? {
+ return Err(Error::ProjectionRevisionConflict);
+ }
let phase: Option<String> = sqlx::query_scalar("SELECT phase FROM radroots_runtime_projection_generations WHERE projection_id=? AND generation=?").bind(scope.projection_id().as_str()).bind(scope.generation().as_bytes().as_slice()).fetch_optional(&mut *transaction).await.map_err(map)?;
let protected = scope.expected_active() == Some(scope.generation())
|| phase.as_deref().is_some_and(|value| value != "retired");
@@ -396,3 +417,7 @@ pub(super) async fn put_snapshot(
#[cfg(test)]
#[path = "cache_tests.rs"]
mod tests;
+
+#[cfg(test)]
+#[path = "cache_legacy_retirement_tests.rs"]
+mod legacy_retirement_tests;
diff --git a/crates/storage_sqlite/src/projection/cache_legacy_retirement_tests.rs b/crates/storage_sqlite/src/projection/cache_legacy_retirement_tests.rs
@@ -0,0 +1,359 @@
+use super::*;
+use crate::{OpenMode, OpenOptions, Paths};
+use radroots_storage::{
+ EventStore, ProjectionStore, Storage,
+ event::{EventSourceToken, SourceGeneration},
+ memory::MemoryStorage,
+ projection::{
+ InvalidationReason, ProjectionCheckpoint, ProjectionDocument, ProjectionGeneration,
+ ProjectionInvalidation, RawSourceDigest, RebuildTicket, RebuildTicketId, RebuildTransition,
+ batch::{ProjectionDocumentBatch, ProjectionWriteScope},
+ },
+};
+use tempfile::TempDir;
+
+fn legacy() -> ProjectionId {
+ ProjectionId::parse("legacy_coordination").unwrap()
+}
+fn rows() -> ProjectionId {
+ ProjectionId::parse("derived_rows").unwrap()
+}
+fn generation(value: u8) -> ProjectionGeneration {
+ ProjectionGeneration::new([value; 32]).unwrap()
+}
+fn limits() -> ProjectionCacheLimits {
+ ProjectionCacheLimits::new(67_108_864, 2, 32, 1_800_000).unwrap()
+}
+fn exact(source: EventSourceToken) -> ProjectionCacheScope {
+ ProjectionCacheScope::new(legacy(), generation(9), source, Some(generation(9))).unwrap()
+}
+fn invalidation() -> ProjectionInvalidation {
+ ProjectionInvalidation::new(
+ legacy(),
+ generation(9),
+ generation(10),
+ InvalidationReason::ProjectionGenerationChanged,
+ 1,
+ )
+ .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 seed(backend: &dyn Storage) {
+ backend
+ .put_projection_document(
+ legacy(),
+ generation(9),
+ ProjectionDocument::new("original".into(), b"legacy".to_vec()).unwrap(),
+ )
+ .await
+ .unwrap();
+ backend
+ .put_projection_snapshot(
+ ProjectionSnapshot::new(legacy(), [3; 32], generation(9), 1, b"snapshot".to_vec())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ backend
+ .checkpoint(ProjectionCheckpoint::new(legacy(), generation(9), None, 1, 1).unwrap())
+ .await
+ .unwrap();
+}
+fn batch(
+ source: EventSourceToken,
+ target: u8,
+ active: Option<ProjectionGeneration>,
+) -> ProjectionDocumentBatch {
+ ProjectionDocumentBatch::new(
+ ProjectionWriteScope::new(rows(), generation(target), source, active).unwrap(),
+ vec![ProjectionDocument::new("row".into(), vec![7]).unwrap()],
+ )
+ .unwrap()
+}
+
+#[tokio::test]
+async fn projection_cache_legacy_retirement_releases_only_metadata_with_memory_sqlite_parity() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ for backend in [&memory as &dyn Storage, &store as &dyn Storage] {
+ seed(backend).await;
+ let source = EventStore::source_token(backend).await.unwrap();
+ backend
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap();
+ assert_eq!(
+ backend.retire_projection_generation(exact(source)).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ backend
+ .retire_projection_generation(exact(EventSourceToken::new(source.generation(), 1)))
+ .await,
+ Err(Error::SourceEpochChanged)
+ );
+ assert_eq!(
+ backend
+ .retire_projection_generation(
+ ProjectionCacheScope::new(legacy(), generation(9), source, None).unwrap()
+ )
+ .await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ backend
+ .promote_projection_batch(
+ batch(source, 1, None),
+ ProjectionCheckpoint::new(rows(), generation(1), None, 1, 2).unwrap(),
+ )
+ .await
+ .unwrap();
+ let before = backend
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap();
+ assert_eq!(before.protected_generations, 2);
+ assert_eq!(
+ backend
+ .put_projection_batch(batch(source, 2, Some(generation(1))))
+ .await,
+ Err(Error::SpaceInsufficient)
+ );
+ let status = backend.invalidate(invalidation()).await.unwrap();
+ let retired = backend
+ .retire_projection_generation(exact(source))
+ .await
+ .unwrap();
+ assert_eq!(retired.protected_generations, 1);
+ assert_eq!(retired.value_bytes, before.value_bytes);
+ assert_eq!(
+ ProjectionStore::status(backend, legacy()).await.unwrap(),
+ Some(status.clone())
+ );
+ assert_eq!(status.health(), ProjectionHealth::Invalidated);
+ assert_eq!(
+ backend
+ .retire_projection_generation(exact(source))
+ .await
+ .unwrap(),
+ retired
+ );
+ assert_eq!(
+ backend.collect_projection_cache(exact(source)).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ backend
+ .projection_document(legacy(), generation(9), "original".into())
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ b"legacy"
+ );
+ assert_eq!(
+ backend
+ .projection_snapshot(legacy(), [3; 32])
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ b"snapshot"
+ );
+ assert_eq!(
+ backend
+ .checkpoint(ProjectionCheckpoint::new(legacy(), generation(9), None, 1, 3).unwrap())
+ .await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ backend
+ .put_projection_batch(batch(source, 2, Some(generation(1))))
+ .await
+ .unwrap();
+ assert_eq!(
+ backend
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap()
+ .protected_generations,
+ 2
+ );
+ }
+}
+
+#[tokio::test]
+async fn projection_cache_legacy_retirement_preserves_refusal_and_counters_on_sqlite_reopen() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ seed(&store).await;
+ let source = store.source_token().await.unwrap();
+ store
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap();
+ let expected = store.invalidate(invalidation()).await.unwrap();
+ let usage = store
+ .retire_projection_generation(exact(source))
+ .await
+ .unwrap();
+ assert_eq!(usage.protected_generations, 0);
+ drop(store);
+ let reopened = open(&temp).await;
+ assert_eq!(
+ ProjectionStore::status(&reopened, legacy()).await.unwrap(),
+ Some(expected)
+ );
+ assert_eq!(
+ reopened
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap(),
+ usage
+ );
+ assert_eq!(
+ reopened
+ .retire_projection_generation(exact(source))
+ .await
+ .unwrap(),
+ usage
+ );
+ assert_eq!(
+ reopened.collect_projection_cache(exact(source)).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ reopened
+ .projection_document(legacy(), generation(9), "original".into())
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ b"legacy"
+ );
+ reopened
+ .promote_projection_batch(
+ batch(source, 1, None),
+ ProjectionCheckpoint::new(rows(), generation(1), None, 1, 2).unwrap(),
+ )
+ .await
+ .unwrap();
+ reopened
+ .put_projection_batch(batch(source, 2, Some(generation(1))))
+ .await
+ .unwrap();
+ assert_eq!(
+ reopened
+ .configure_projection_cache(rows(), limits())
+ .await
+ .unwrap()
+ .protected_generations,
+ 2
+ );
+}
+
+#[tokio::test]
+async fn projection_cache_legacy_retirement_refuses_requested_and_running_rebuilds() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ for backend in [&memory as &dyn Storage, &store as &dyn Storage] {
+ seed(backend).await;
+ let source = EventStore::source_token(backend).await.unwrap();
+ backend.invalidate(invalidation()).await.unwrap();
+ let requested = backend
+ .request_rebuild(
+ RebuildTicket::requested(
+ RebuildTicketId::new([4; 16]).unwrap(),
+ invalidation(),
+ source.generation(),
+ None,
+ RawSourceDigest::new([1; 32]),
+ )
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ let before = ProjectionStore::status(backend, legacy()).await.unwrap();
+ assert_eq!(
+ backend.retire_projection_generation(exact(source)).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ ProjectionStore::status(backend, legacy()).await.unwrap(),
+ before
+ );
+ backend
+ .transition_rebuild(RebuildTransition::start(
+ requested.ticket_id(),
+ requested.revision(),
+ 2,
+ ))
+ .await
+ .unwrap();
+ let before = ProjectionStore::status(backend, legacy()).await.unwrap();
+ assert_eq!(
+ backend.retire_projection_generation(exact(source)).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ ProjectionStore::status(backend, legacy()).await.unwrap(),
+ before
+ );
+ }
+}
+
+#[tokio::test]
+async fn projection_cache_legacy_retirement_refuses_live_unconfigured_batch_registration() {
+ let temp = TempDir::new().unwrap();
+ let store = open(&temp).await;
+ let memory = MemoryStorage::new(SourceGeneration::new([9; 32]).unwrap());
+ for backend in [&memory as &dyn Storage, &store as &dyn Storage] {
+ let source = EventStore::source_token(backend).await.unwrap();
+ backend
+ .promote_projection_batch(
+ batch(source, 1, None),
+ ProjectionCheckpoint::new(rows(), generation(1), None, 1, 2).unwrap(),
+ )
+ .await
+ .unwrap();
+ backend
+ .invalidate(
+ ProjectionInvalidation::new(
+ rows(),
+ generation(1),
+ generation(2),
+ InvalidationReason::OperatorRequested,
+ 3,
+ )
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ let scope =
+ ProjectionCacheScope::new(rows(), generation(1), source, Some(generation(1))).unwrap();
+ assert_eq!(
+ backend.retire_projection_generation(scope).await,
+ Err(Error::ProjectionRevisionConflict)
+ );
+ assert_eq!(
+ backend
+ .projection_document(rows(), generation(1), "row".into())
+ .await
+ .unwrap()
+ .unwrap()
+ .value(),
+ &[7]
+ );
+ }
+}