lib

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

commit 27c3118d435cb57f69464cbbdad25dec0c69369a
parent 05ad0ff0f521535f7649027d4f3391e6464f7fa1
Author: triesap <tyson@radroots.org>
Date:   Fri, 23 Oct 2026 22:49:52 +0000

sync: preserve original wire bytes during local admission

- Reconcile equivalent signed wire values after an explicit canonical byte conflict.
- Bound reconciliation to one exact identifier read and one verified admission retry.
- Preserve canonical, signed artifact and delivery bytes across memory and SQLite reopen.
- Verify Sync tests, portable checks, strict lint, exact API and unchanged coverage gates.

Diffstat:
Mcontracts/architecture/deviations.toml | 21+++++++++++++++++++++
Mcrates/sync/README.md | 13++++++++++++-
Mcrates/sync/src/push.rs | 13+++++++++++--
Acrates/sync/src/push/admission.rs | 47+++++++++++++++++++++++++++++++++++++++++++++++
Mcrates/sync/tests/push_enqueue.rs | 3+++
Acrates/sync/tests/push_enqueue/wire_admission.rs | 282+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 376 insertions(+), 3 deletions(-)

diff --git a/contracts/architecture/deviations.toml b/contracts/architecture/deviations.toml @@ -2,6 +2,27 @@ schema_version = 1 architecture_id = "radroots.crates.release.v1" [[deviation]] +id = "RCRV1-DEV-058" +date = "2026-10-23" +status = "active" +approval = "The user authorizes the complete approved refactor, necessary supported dependency corrections, verified owning commits and source publication." +affected_steps = ["050", "060", "070", "130", "140"] +spec_anchors = ["contracts/crates/release_v1/radroots_crates_release_v1.toml#package.radroots_sync"] +source_evidence = [ + "Raw-preserving source admission exposes a deterministic authored-admission failure when an incoming copy of the original signed event precedes local admission with different JSON whitespace or object-key ordering.", + "The canonical event store deliberately rejects byte conflicts. The retained signing artifact and the first canonical raw event must both remain immutable; weakening storage equality or re-signing would lose original evidence.", +] +replacement_action = "Before qualifying further consumer artifacts, reconcile this shared push-admission boundary. Following an explicit event conflict, read at most one exact identifier and retry admission at most once using the stored bytes only when the complete signed wire value, including signature and extension fields, matches. Revalidate the stored event and retain all original artifact/delivery bytes." +verification = [ + "Exercise real signatures with both memory and SQLite stores, retain exact canonical and original artifact bytes, preserve extension/signature conflicts and verify explicit close/reopen and admission replay.", + "Run the complete affected shared push tests, package check/lint/docs, contract/architecture and portable feature checks; keep the consumer failure and earlier source-bound results unchanged.", + "Publish the verified provider before exact supported consumer and artifact adoption; no earlier candidate or prepared pin qualifies the successor.", +] +unresolved_risk = "Exact successor consumer and artifact adoption remains pending; provider qualification does not establish application restore, browser artifact, physical-device or full refactor acceptance." +normative_architecture_change = false +adr_required = false + +[[deviation]] id = "RCRV1-DEV-057" date = "2026-10-23" status = "active" diff --git a/crates/sync/README.md b/crates/sync/README.md @@ -16,7 +16,18 @@ pulling native SQLite test dependencies into the browser target. `StorageSpaceInsufficient` preserves the storage owner's typed capacity failure. It does not establish rollback or absence of signer or remote effects. Retain the original requests, signed bytes and unresolved receipts, then reconcile -existing state before retrying. Sync never frees storage or retries implicitly. +existing state before retrying. Storage cleanup and future retry scheduling +remain host-owned. + +Local authored admission preserves an already stored event's original JSON. +After a byte conflict, it reads at most one matching identifier and retries +admission once only when the complete signed wire value matches, including +signature and extension fields. It verifies that stored value again before +advancing admission. The original signing artifact and delivery bytes remain +unchanged; identifier equality alone never permits this reconciliation. +Both representations must satisfy the duplicate-free, seven-field NIP-01 +profile with a 64 KiB byte limit. Other storage conflicts retain their +existing failure classification. Ingest performs real event-ID and signature verification before host policy. Contract failure defaults to rejection. A host can explicitly retain such a diff --git a/crates/sync/src/push.rs b/crates/sync/src/push.rs @@ -28,7 +28,7 @@ use radroots_storage::{ AuthoredDeliveryPlanId, AuthoredDeliveryState, DELIVERY_PLAN_ATTEMPTS_MAX, DeliveryAttemptOutcome, }, - event::{AdmissionDisposition, EventAdmission, EventStore}, + event::{AdmissionDisposition, EventAdmission}, journal::{IdempotencyKey, OperationInstanceId}, }; use radroots_transport::{ @@ -46,6 +46,7 @@ use crate::{ policy::{Error, OperationKind, SyncId}, }; +mod admission; mod delivery; const SIGNING_CLAIM_OWNER_EXACT: &str = "radroots-sync-signing-exact"; @@ -807,7 +808,15 @@ impl Engine { return Err(error); } }; - let admission_receipt = match EventStore::admit(self.storage.as_ref(), admission).await { + let admission_receipt = match admission::admit( + self.storage.as_ref(), + admission, + &event, + contract_id, + now, + ) + .await + { Ok(receipt) => receipt, Err(error) => { let applied_at = self.clock.now_unix_ms()?.max(claimed.updated_at_unix_ms()); diff --git a/crates/sync/src/push/admission.rs b/crates/sync/src/push/admission.rs @@ -0,0 +1,47 @@ +use radroots_event::SignedEvent; +use radroots_event::wire::{EventWireLimits, Nip01EventWire}; +use radroots_storage::{ + Error, EventStore, + event::{AdmissionReceipt, EventAdmission, EventQuery, EventQueryBounds}, +}; + +use crate::policy::SyncStorage; + +pub(super) async fn admit( + storage: &dyn SyncStorage, + admission: EventAdmission, + original: &SignedEvent, + contract_id: &str, + observed_at_unix_ms: u64, +) -> Result<AdmissionReceipt, Error> { + match EventStore::admit(storage, admission).await { + Err(Error::EventConflict) => {} + result => return result, + } + + let query = EventQuery::for_ids(EventQueryBounds::first(1)?, vec![*original.id()])?; + let existing = EventStore::query_raw(storage, query).await?; + let [stored] = existing.items() else { + return Err(Error::EventConflict); + }; + // Wire equality includes the signature and extension fields. The canonical + // store keeps its first raw bytes; the signing artifact keeps its own. + if stored.event().wire() != original.wire() + || !exact_wire(stored.event()) + || !exact_wire(original) + { + return Err(Error::EventConflict); + } + let canonical = super::outbound_admission(stored.event(), contract_id, observed_at_unix_ms) + .map_err(|_| Error::EventConflict)?; + EventStore::admit(storage, canonical).await +} + +fn exact_wire(event: &SignedEvent) -> bool { + let limits = EventWireLimits { + max_raw_json_bytes: 64 * 1024, + ..EventWireLimits::default() + }; + Nip01EventWire::parse_json_exact_with_limits(event.raw_json(), limits) + .is_ok_and(|wire| &wire == event.wire()) +} diff --git a/crates/sync/tests/push_enqueue.rs b/crates/sync/tests/push_enqueue.rs @@ -66,6 +66,9 @@ mod delivery_selection; #[path = "push_enqueue/capacity.rs"] mod capacity; +#[path = "push_enqueue/wire_admission.rs"] +mod wire_admission; + struct MockSink; struct FaultStorage { diff --git a/crates/sync/tests/push_enqueue/wire_admission.rs b/crates/sync/tests/push_enqueue/wire_admission.rs @@ -0,0 +1,282 @@ +use super::*; +use radroots_event::admission::RawEvent; +use radroots_event_codec::verify::{self, Nip01SignatureVerifier}; +use radroots_storage::event::{AdmissionStage, EventAdmission}; +use radroots_transport::source::{EventProvenance, ObservedEvent}; + +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +enum Variant { + Reordered, + Limit, + Extra, + Signature, + Duplicate, + Oversize, +} + +impl Variant { + fn permits_admission(self) -> bool { + matches!(self, Self::Reordered | Self::Limit) + } +} + +fn verified_admission(event: SignedEvent) -> EventAdmission { + let target = Target::new(TransportId::NOSTR, "wss://relay.example").expect("target"); + let verified = verify::signature( + verify::id(RawEvent::new(event.envelope().clone())).expect("identifier"), + &Nip01SignatureVerifier, + ) + .expect("actual Schnorr signature"); + let observed = ObservedEvent::new( + event, + EventProvenance::new( + TransportId::NOSTR, + target.fingerprint().clone(), + 1_800_000_200_000, + ) + .expect("provenance"), + ); + EventAdmission::verified(observed, verified).expect("verified incoming event") +} + +fn alternate(original: &SignedEvent, variant: Variant) -> SignedEvent { + let mut value: serde_json::Value = + serde_json::from_str(original.raw_json()).expect("wire JSON"); + match variant { + Variant::Extra => value["future_attribute"] = serde_json::json!("retained extension"), + Variant::Signature => { + value["sig"] = serde_json::json!( + Secp256k1::new() + .sign_schnorr_with_aux_rand( + &Message::from_digest(*original.id().as_bytes()), + &signing_keypair(), + &[2; 32], + ) + .to_string() + ); + } + _ => {} + } + let mut raw = serde_json::to_string_pretty(&value).expect("alternate serialization"); + if variant == Variant::Duplicate { + assert_eq!(raw.pop(), Some('}')); + raw.push_str(&format!(",\"id\":\"{}\"}}", original.id().to_hex())); + } + if matches!(variant, Variant::Limit | Variant::Oversize) { + let limit = 64 * 1024 + usize::from(variant == Variant::Oversize); + raw.insert_str(0, &" ".repeat(limit - raw.len())); + assert_eq!(raw.len(), limit); + } + let wire = radroots_event::wire::Nip01EventWire::parse_json(&raw).expect("valid identifier"); + SignedEvent::from_wire_verified_id(wire, raw).expect("exact raw/wire binding") +} + +async fn exercise( + storage: Arc<dyn SyncStorage>, + variant: Variant, +) -> (SignedEvent, SignedEvent, SyncId) { + let sink = Arc::new(ScriptedSink::new([DeliveryBehavior::Outcomes(vec![ + DeliveryOutcome::accepted(), + ])])); + let signer = Arc::new(MockSigner::new(SignBehavior::Success { + completed_at_unix_ms: 1_800_000_200_500, + })); + let engine = Engine::builder( + storage.clone(), + Arc::new(TestClock(AtomicU64::new(1_800_000_200_000))), + Arc::new(TestIds(AtomicU64::new(10))), + DeadlinePolicy::new(10_000, 10_000, 10_000).expect("deadlines"), + ) + .sink(sink.clone()) + .signer(signer.clone()) + .build() + .expect("engine"); + let push = request(119, "wss://relay.example"); + let signed = engine + .sign_prepared(push.clone()) + .await + .expect("actual signed artifact"); + let original = signed + .artifact() + .signed() + .expect("signed bytes") + .event() + .clone(); + let remote = alternate(&original, variant); + assert_ne!(remote.raw_json(), original.raw_json()); + assert_eq!(remote.id(), original.id()); + assert_eq!( + remote.wire() == original.wire(), + !matches!(variant, Variant::Extra | Variant::Signature) + ); + EventStore::admit(storage.as_ref(), verified_admission(remote.clone())) + .await + .expect("initial canonical observation"); + // The store's strict byte-conflict invariant remains in force. + assert_eq!( + EventStore::admit(storage.as_ref(), verified_admission(original.clone())).await, + Err(radroots_storage::Error::EventConflict) + ); + + let result = engine.admit_signed(push.operation_id()).await; + if variant.permits_admission() { + assert!( + result + .expect("equivalent-wire admission") + .artifact() + .admission_state() + .is_admitted() + ); + assert!( + engine + .admit_signed(push.operation_id()) + .await + .expect("exact admission replay") + .is_replay() + ); + engine + .deliver_push(push.operation_id()) + .await + .expect("original delivery"); + let requests = sink.requests.lock().expect("delivery records"); + assert_eq!(requests.len(), 1); + assert_eq!( + requests[0].payload().event().raw_json(), + original.raw_json() + ); + } else { + assert_eq!(result, Err(Error::AdmissionFailed)); + } + let status = engine + .push_status(push.operation_id()) + .await + .expect("status") + .expect("retained operation"); + assert_eq!( + status + .artifact() + .signed() + .expect("original artifact") + .event() + .raw_json(), + original.raw_json() + ); + assert_eq!(signer.calls.load(Ordering::Relaxed), 1); + let canonical = EventStore::query_raw( + storage.as_ref(), + EventQuery::for_ids( + EventQueryBounds::first(1).expect("bounds"), + vec![*original.id()], + ) + .expect("identifier query"), + ) + .await + .expect("canonical event"); + assert_eq!(canonical.items().len(), 1); + assert_eq!(canonical.items()[0].event().raw_json(), remote.raw_json()); + assert_eq!( + canonical.items()[0].stage(), + if variant.permits_admission() { + AdmissionStage::Visible + } else { + AdmissionStage::Verified + } + ); + (original, remote, push.operation_id()) +} + +#[test] +fn memory_wire_variants_preserve_both_originals_and_refuse_profile_or_signature_changes() { + for (generation, variant) in [ + (81, Variant::Reordered), + (82, Variant::Limit), + (83, Variant::Extra), + (84, Variant::Signature), + (85, Variant::Duplicate), + (86, Variant::Oversize), + ] { + block_on(exercise( + Arc::new(MemoryStorage::new( + SourceGeneration::new([generation; 32]).expect("generation"), + )), + variant, + )); + } +} + +#[tokio::test] +async fn sqlite_wire_variants_preserve_both_originals_across_explicit_close_and_reopen() { + for (generation, variant) in [ + (91, Variant::Reordered), + (92, Variant::Limit), + (93, Variant::Extra), + (94, Variant::Signature), + (95, Variant::Duplicate), + (96, Variant::Oversize), + ] { + let directory = tempfile::tempdir().expect("database directory"); + let paths = Paths::from_directory(directory.path()).expect("paths"); + let storage = Arc::new( + SqliteStorage::open( + OpenOptions::new(paths.clone(), OpenMode::Create) + .with_source_generation( + SourceGeneration::new([generation; 32]).expect("generation"), + 1, + ) + .expect("source generation"), + ) + .await + .expect("SQLite"), + ); + let (original, remote, operation_id) = exercise(storage.clone(), variant).await; + storage.close().await.expect("explicit close"); + let reopened = Arc::new( + SqliteStorage::open(OpenOptions::new(paths, OpenMode::ReadOnly)) + .await + .expect("read-only reopen"), + ); + let events = reopened + .query_raw(EventQuery::all(EventQueryBounds::first(1).expect("bounds"))) + .await + .expect("retained canonical row"); + assert_eq!(events.items().len(), 1); + assert_eq!(events.items()[0].event().raw_json(), remote.raw_json()); + assert_eq!( + events.items()[0].stage(), + if variant.permits_admission() { + AdmissionStage::Visible + } else { + AdmissionStage::Verified + } + ); + let inspection: Arc<dyn SyncStorage> = reopened.clone(); + let reader = Engine::builder( + inspection, + Arc::new(TestClock(AtomicU64::new(1_800_000_201_000))), + Arc::new(TestIds(AtomicU64::new(100))), + DeadlinePolicy::new(10_000, 10_000, 10_000).expect("deadlines"), + ) + .sink(Arc::new(MockSink)) + .build() + .expect("read-only inspection without signer"); + let status = reader + .push_status(operation_id) + .await + .expect("read-only status") + .expect("original operation"); + assert_eq!( + status + .artifact() + .signed() + .expect("original retained evidence") + .event() + .raw_json(), + original.raw_json() + ); + assert_eq!( + status.artifact().admission_state().is_admitted(), + variant.permits_admission() + ); + reopened.close().await.expect("close inspection"); + } +}