commit 7388ebdbe3070664dcd5546ffdb05dfe212e5313
parent 57659af2ca92fe08b27c15c37f7995cf214253b2
Author: triesap <tyson@radroots.org>
Date: Mon, 12 Oct 2026 02:00:02 +0000
sync: validate deserialized projection request bounds
- Route refresh-request JSON admission through the checked constructor.
- Reject zero and oversized batch bounds before they can reach engine orchestration.
- Preserve valid boundary round-trips, wire shape and existing unknown-field behavior.
- Verify the failing baseline and Rust 1.99.0 format, check, full tests, serde-disabled build, Clippy and architecture controls.
Diffstat:
4 files changed, 105 insertions(+), 1 deletion(-)
diff --git a/contracts/architecture/deviations.toml b/contracts/architecture/deviations.toml
@@ -2,6 +2,34 @@ schema_version = 1
architecture_id = "radroots.crates.release.v1"
[[deviation]]
+id = "RCRV1-DEV-027"
+date = "2026-10-12"
+status = "closed"
+approval = "The user approved the full successor refactor and local verified checkpoint commits; publication and integrated acceptance remain separate."
+affected_steps = ["010", "040", "130"]
+spec_anchors = ["contracts/crates/release_v1/radroots_crates_release_v1.toml#package.radroots_sync"]
+source_evidence = [
+ "A bounded public-API probe decoded batch_limit and max_batches values zero and 1001 even though RefreshRequest::new rejects them.",
+ "The real engine panicked at its unreachable zero-batch branch after receiving the invalid deserialized request; the isolated probe observed no network or durable effects.",
+ "Derived deserialization bypasses the request's constructor invariants, leaving source-level field privacy insufficient admission protection.",
+]
+replacement_action = "Bring forward the contained request-admission correction during source review: deserialize through the checked constructor, preserve existing valid wire and unknown-field policy, and keep projection ownership, bounds, public APIs and features unchanged."
+verification = [
+ "Validate the standalone deviation before changing production request deserialization.",
+ "Record a failing invalid-JSON regression on the original source, then reject zero/upper-bound violations and round-trip valid lower/upper boundary requests.",
+ "Run exact Rust 1.99.0 scoped format, all-target check, full sync tests, serde-disabled library check and all-target warnings-as-errors Clippy; review the exact source diff before a local owner commit.",
+]
+unresolved_risk = "The contained JSON admission repair is locally verified. Supported consumer adoption and broader request/binding/platform qualification remain separate and pending."
+normative_architecture_change = false
+adr_required = false
+closure_evidence = [
+ "The invalid-JSON regression failed on unchanged production source, then passed after routing deserialization through RefreshRequest::new. Zero and above-maximum values for both fields are rejected before orchestration.",
+ "Valid lower/upper request bounds round-trip with the existing wire shape and unknown-field policy; the original public engine-panic probe remains immutable baseline evidence.",
+ "Exact Rust 1.99.0 scoped formatting, all-target check, full sync package tests, serde-disabled library check and all-target warnings-as-errors Clippy passed on local macOS arm64.",
+ "Only deserialization, its regression, package guidance and this deviation changed. Public types, constructor bounds, features, dependencies, storage/reducer ownership and generated API shapes are unchanged.",
+]
+
+[[deviation]]
id = "RCRV1-DEV-026"
date = "2026-10-12"
status = "closed"
diff --git a/crates/sync/README.md b/crates/sync/README.md
@@ -17,6 +17,10 @@ signed observation through `AdmissionPolicy::contract_failure` for canonical
replacement evidence; its closed decision permits only rejection or verified
retention, never visibility. Invalid IDs and signatures cannot reach this policy.
+Projection refresh JSON uses the same checked constructor as native requests.
+Zero or oversized batch bounds are rejected before storage or reducer work;
+valid boundary values and the existing wire shape remain unchanged.
+
Pull receipts retain the last available outcome for each target and bounded
cumulative target summaries across returned pages. A later complete outcome
does not erase an earlier incomplete or missing outcome. Summaries preserve
diff --git a/crates/sync/src/projection.rs b/crates/sync/src/projection.rs
@@ -27,7 +27,7 @@ pub const PROJECTION_RAW_SOURCE_MAX_EVENTS: u64 = 1_000_000;
const RAW_SOURCE_DIGEST_DOMAIN: &[u8] = b"radroots:projection:raw-source:v1\0";
/// Bounded refresh request for one exact reducer generation.
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RefreshRequest {
projection_id: ProjectionId,
@@ -75,6 +75,31 @@ impl RefreshRequest {
}
}
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for RefreshRequest {
+ fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+ where
+ D: serde::Deserializer<'de>,
+ {
+ #[derive(serde::Deserialize)]
+ struct Wire {
+ projection_id: ProjectionId,
+ generation: ProjectionGeneration,
+ batch_limit: u16,
+ max_batches: u16,
+ }
+
+ let wire = Wire::deserialize(deserializer)?;
+ Self::new(
+ wire.projection_id,
+ wire.generation,
+ wire.batch_limit,
+ wire.max_batches,
+ )
+ .map_err(serde::de::Error::custom)
+ }
+}
+
/// Owning-domain deterministic reducer capability.
///
/// Reducers own domain semantics and projected row calculation. They receive
diff --git a/crates/sync/tests/projection.rs b/crates/sync/tests/projection.rs
@@ -263,6 +263,53 @@ fn incremental_refresh_checkpoints_visible_events() {
);
}
+#[cfg(feature = "serde")]
+#[test]
+fn serialized_refresh_requests_enforce_constructor_bounds() {
+ use radroots_storage::event::EVENT_QUERY_LIMIT_MAX;
+ use radroots_sync::projection::PROJECTION_REFRESH_MAX_BATCHES;
+
+ let id = ProjectionId::parse("wire.projection").unwrap();
+ let generation = ProjectionGeneration::new([2; 32]).unwrap();
+ let original = RefreshRequest::new(id.clone(), generation, 1, 1).unwrap();
+ let wire = serde_json::to_value(&original).unwrap();
+ for (batch_limit, max_batches) in [
+ (0, 1),
+ (EVENT_QUERY_LIMIT_MAX + 1, 1),
+ (1, 0),
+ (1, PROJECTION_REFRESH_MAX_BATCHES + 1),
+ ] {
+ assert!(RefreshRequest::new(id.clone(), generation, batch_limit, max_batches).is_err());
+ let mut changed = wire.clone();
+ changed["batch_limit"] = serde_json::json!(batch_limit);
+ changed["max_batches"] = serde_json::json!(max_batches);
+ assert!(
+ serde_json::from_value::<RefreshRequest>(changed).is_err(),
+ "batch_limit={batch_limit}, max_batches={max_batches}"
+ );
+ }
+ for (batch_limit, max_batches) in [
+ (1, 1),
+ (EVENT_QUERY_LIMIT_MAX, 1),
+ (1, PROJECTION_REFRESH_MAX_BATCHES),
+ (EVENT_QUERY_LIMIT_MAX, PROJECTION_REFRESH_MAX_BATCHES),
+ ] {
+ let request =
+ RefreshRequest::new(id.clone(), generation, batch_limit, max_batches).unwrap();
+ let mut wire = serde_json::to_value(&request).unwrap();
+ assert_eq!(
+ serde_json::from_value::<RefreshRequest>(wire.clone()).unwrap(),
+ request
+ );
+ wire["application_extension"] = serde_json::json!(true);
+ assert_eq!(
+ serde_json::from_value::<RefreshRequest>(wire).unwrap(),
+ request,
+ "the existing unknown-field policy is unchanged"
+ );
+ }
+}
+
#[test]
fn generation_change_rebuilds_and_reducer_failure_is_durable() {
let (engine, storage, id) = setup();