From 4124e9c61d28a9a894ad4f8215448ca2512f9c62 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 24 Sep 2026 19:32:02 +0200 Subject: [PATCH] feat: add reproducible named event random draws --- AGENTS-TASKS.md | 8 +- Cargo.lock | 1 + docs/deterministic-execution-design.md | 21 +- docs/epoch-resolution-tasks.md | 11 +- lib_efo/Cargo.toml | 1 + lib_efo/src/event_rng.rs | 256 +++++++++++++++++++++++++ lib_efo/src/lib.rs | 1 + lib_efo/tests/epoch_resolution.rs | 30 +++ 8 files changed, 322 insertions(+), 7 deletions(-) create mode 100644 lib_efo/src/event_rng.rs diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index d023a04..76fac13 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -261,9 +261,13 @@ and [`docs/presentation-design.md`](docs/presentation-design.md). ### Deterministic execution design - Active implementation: [epoch resolution task list](docs/epoch-resolution-tasks.md). -- Updated decision: all resolution commands share a persisted epoch baseline; +- [x] All resolution commands share a persisted epoch baseline; clamp each independent ruling, sum its effective contribution, clamp the total. Commit/epoch-next is the compounding boundary. +- [x] Publish format 1.1 with 1.0 reads, atomic upgrade, full stale-state checks, + complete-resolution stage/restore, historical validation, and CLI permutation tests. +- [x] Add pinned event-local ChaCha12 named draws; keep GM rolls external and + preserve the existing worldgen algorithm. Actual worker pools remain future work. - [x] Document immutable batch inputs, event/occurrence RNG identities, exact delta reduction, normalization, retries, phase barriers, and atomic publication @@ -279,7 +283,7 @@ and [`docs/presentation-design.md`](docs/presentation-design.md). - [x] Implement a versioned serial batch reference and proposal/receipt schema with compatibility fixtures before introducing a worker pool. - [x] Convert mental checks into executable permutation, retry, stale-state, - arithmetic and recovery tests; RNG golden vectors are the next increment. + arithmetic, recovery, and event-local RNG golden-vector tests. ### Presentation completion (#10) diff --git a/Cargo.lock b/Cargo.lock index eeb84f4..a18ac4a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -652,6 +652,7 @@ dependencies = [ "miette", "once_cell", "rand", + "rand_chacha", "serde", "serde_json", "tempfile", diff --git a/docs/deterministic-execution-design.md b/docs/deterministic-execution-design.md index 08dad9c..d7dd8a5 100644 --- a/docs/deterministic-execution-design.md +++ b/docs/deterministic-execution-design.md @@ -34,8 +34,11 @@ arrivals and conflict rounds remains explicit and ordered. ## Randomness and task identity Use seed plus a stable event hash as a keyed derivation, not arithmetic addition -or Rust's default hash. Define a versioned, canonical, length-delimited encoding -and a pinned hash and RNG algorithm before implementation. Map/set entries use +or Rust's default hash. `event_rng::EventRandom` implements +`epoch-forge/event-rng-chacha12-fnv-v1`: four domain-labelled FNV-1a-64 lanes +derive a 256-bit seed for pinned `rand_chacha` 0.9.0 `ChaCha12Rng`. Each field +has a u64 little-endian byte-length prefix; integer fields and output hash lanes +use little endian, UUIDs use their standard 16-byte representation. Map/set entries use stable key order; integers have fixed width and byte order. Do not hash display text, memory addresses, paths, worker numbers, or mutable output fields. @@ -56,13 +59,25 @@ draws. An intentionally lifetime-fixed event roll omits tick/round explicitly. Event-wide shared draws omit the target explicitly; independent target draws include it. Named substreams prevent a new cosmetic draw or target from shifting existing outcomes. Pin bounded-integer sampling and rejection behavior as well -as the underlying generator, with golden vectors. +as the underlying generator, with golden vectors. The implemented `below` +method rejects draws below `2^64 mod upper`, then returns `draw mod upper`. +Each rejection has an independent retry index, capped at 1024 attempts. +Golden vectors cover both accepted-first and rejected-first draws. Hash equality must not silently merge different tasks: retain canonical identity alongside the digest and reject a detected collision. Content identity is not application identity: two intentional identical rulings need distinct occurrence IDs, while a retry must retain the original ID. +The high-level `for_event` helper reads the frozen event definition and seed, +combines them with the epoch ID, event UUID, occurrence number, and caller's +rules/configuration, and sorts JSON object keys recursively. Arrays retain +semantic order. `draw(target, purpose, index)` is immutable and random-access; +`None` means an event-wide draw and differs from even a nil target UUID. Event +key derivation is deterministic and noncryptographic; it is not a security API. +The caller owns versioned purpose labels and occurrence IDs. Do not feed worker +indices, current time, or unordered semantic arrays into that identity. + Adjudication remains an external player roll and explicit GM decision. These RNG rules authorize no automatic adjudication rolls. Current world generation uses one sequential `StdRng` stream in `worldgen::generate`; its seed alone does diff --git a/docs/epoch-resolution-tasks.md b/docs/epoch-resolution-tasks.md index 61da8b0..70ba6a1 100644 --- a/docs/epoch-resolution-tasks.md +++ b/docs/epoch-resolution-tasks.md @@ -28,9 +28,9 @@ round lifecycle and explicit diffusion arrival bookkeeping remain ordered. - [x] Persist resolutions with a full stale-snapshot check under the writer lock; integrate staging, restore, revert, historical validation, and format compatibility safeguards. -- [ ] Add deterministic event-local named random draws with pinned encoding and +- [x] Add deterministic event-local named random draws with pinned encoding and golden vectors, without introducing RNG into externally adjudicated rulings. -- [ ] Update command/help/repository documentation and CLI workflow tests; run +- [x] Update command/help/repository documentation and CLI workflow tests; run formatting, locked all-feature workspace tests, and strict Clippy before each implementation commit. @@ -61,3 +61,10 @@ Checkpoint 2: all resolution command families use the reducer; format-1.1 publication validates the full snapshot under lock. Integration tests exercise mixed-command order, staging/restore, compounding, compatibility, locks, interrupted transactions, stale input, and revert. + +Checkpoint 3: immutable event-local ChaCha12 draws use explicit seed/epoch/event/ +occurrence identities and named target/purpose/index keys. Generator and encoding +versions are pinned; golden vectors were cross-checked with an independent +Python FNV/ChaCha12 reference calculation. GM rulings and existing worldgen do +not call this API. No worker pool, transfer allocation, or automatic event +scheduling is introduced by this feature. diff --git a/lib_efo/Cargo.toml b/lib_efo/Cargo.toml index 4a86019..d9a866d 100644 --- a/lib_efo/Cargo.toml +++ b/lib_efo/Cargo.toml @@ -19,6 +19,7 @@ cli-table = "0.5.0" colored = {workspace = true} uuid = {workspace = true} rand = "0.9.2" +rand_chacha = "=0.9.0" once_cell = "1.21.3" tempfile = "3.23.0" diff --git a/lib_efo/src/event_rng.rs b/lib_efo/src/event_rng.rs new file mode 100644 index 0000000..1902db0 --- /dev/null +++ b/lib_efo/src/event_rng.rs @@ -0,0 +1,256 @@ +//! Versioned random-access event randomness, independent of worker scheduling. +//! +//! This is a simulation utility, not a source of adjudication rolls or secrets. +//! It does not change the existing sequential world-generation algorithm. + +use rand::{RngCore, SeedableRng}; +use rand_chacha::ChaCha12Rng; +use serde::Serialize; +use uuid::Uuid; + +use crate::{epoch::EpochInfo, stats::EntityType}; + +/// Encoding, key derivation, generator, and bounded sampling contract. +pub const ALGORITHM: &str = "epoch-forge/event-rng-chacha12-fnv-v1"; + +/// Failures preparing or sampling an event-local random stream. +#[derive(Debug, thiserror::Error)] +pub enum EventRandomError { + /// The selected event is not in the frozen inputs. + #[error("cannot prepare event randomness: {0}")] + Event(#[from] crate::error::EpochError), + /// Inputs could not be converted to canonical JSON. + #[error("cannot encode event randomness inputs: {0}")] + Encoding(#[from] serde_json::Error), + /// An empty range has no sample. + #[error("event random upper bound must be greater than zero")] + EmptyRange, + /// The bounded deterministic rejection budget was exceeded. + #[error("event random sampling exceeded its rejection budget")] + RejectionLimit, +} + +/// An immutable event key. Clone/share freely; draws never advance shared state. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct EventRandom { + /// Domain-separated 256-bit seed derived from all declared event inputs. + key: [u8; 32], +} + +impl EventRandom { + /// Prepare a key from explicit inputs. Definitions must use a caller-owned + /// canonical, versioned encoding; changing their bytes changes the stream. + pub fn new( + seed: u64, + epoch: u64, + event: Uuid, + occurrence: u64, + event_definition: &[u8], + rules_definition: &[u8], + ) -> Self { + Self { + key: derive(&[ + ALGORITHM.as_bytes(), + b"event", + &seed.to_le_bytes(), + &epoch.to_le_bytes(), + event.as_bytes(), + &occurrence.to_le_bytes(), + event_definition, + rules_definition, + ]), + } + } + + /// Use this epoch's frozen event and seed plus canonical JSON rule inputs. + /// Object keys sort recursively; array order remains semantically significant. + /// The occurrence must be stable input, never a queue/worker index. + pub fn for_event( + world: &EpochInfo, + event: Uuid, + occurrence: u64, + rules: &impl Serialize, + ) -> Result { + let baseline = crate::epoch_resolution::inputs(world); + let definition = baseline.find_entity_strict(event, Some(EntityType::Event))?; + Ok(Self::new( + baseline.rng_seed, + world.epoch_id.id, + event, + occurrence, + &canonical_json(definition)?, + &canonical_json(rules)?, + )) + } + + /// Return one independent u64 draw. `None` requests a shared event-wide draw; + /// `Some(target)` requests an independent target draw. Purpose labels and + /// draw indices are stable identities, not counts of previously consumed draws. + pub fn draw(&self, target: Option, purpose: &str, index: u64) -> u64 { + self.attempt(target, purpose, index, 0) + } + + /// Uniform sample in `0..upper`, with a pinned rejection algorithm. Rejections + /// use a separate retry index and cannot shift any other named draw. + pub fn below( + &self, + target: Option, + purpose: &str, + index: u64, + upper: u64, + ) -> Result { + if upper == 0 { + return Err(EventRandomError::EmptyRange); + } + let threshold = upper.wrapping_neg() % upper; + for retry in 0..1024 { + let value = self.attempt(target, purpose, index, retry); + if value >= threshold { + return Ok(value % upper); + } + } + Err(EventRandomError::RejectionLimit) + } + + /// Construct a local generator for exactly this draw/retry identity. + fn attempt(&self, target: Option, purpose: &str, index: u64, retry: u64) -> u64 { + let target_bytes = target.map_or_else(Vec::new, |id| id.as_bytes().to_vec()); + let seed = derive(&[ + ALGORITHM.as_bytes(), + b"draw", + &self.key, + &target_bytes, + purpose.as_bytes(), + &index.to_le_bytes(), + &retry.to_le_bytes(), + ]); + ChaCha12Rng::from_seed(seed).next_u64() + } +} + +/// Four independently domain-labelled FNV-1a-64 lanes, wrapping mod 2^64. +/// Each field has an unsigned u64 little-endian byte length prefix. Output lanes +/// use little endian. This fixed noncryptographic derivation is versioned above. +fn derive(fields: &[&[u8]]) -> [u8; 32] { + let mut key = [0; 32]; + for lane in 0_u8..4 { + let mut hash = 0xcbf2_9ce4_8422_2325_u64; + for byte in [lane] + .iter() + .copied() + .chain(fields.iter().flat_map(|field| { + (field.len() as u64) + .to_le_bytes() + .into_iter() + .chain(field.iter().copied()) + })) + { + hash = (hash ^ u64::from(byte)).wrapping_mul(0x0000_0100_0000_01b3); + } + let start = usize::from(lane) * 8; + key[start..start + 8].copy_from_slice(&hash.to_le_bytes()); + } + key +} + +/// Canonical JSON object ordering independent of struct/hash-map insertion order. +fn canonical_json(value: &impl Serialize) -> Result, serde_json::Error> { + /// Recursively sort object keys without reordering arrays. + fn ordered(value: serde_json::Value) -> serde_json::Value { + match value { + serde_json::Value::Object(map) => { + let mut entries = map.into_iter().collect::>(); + entries.sort_by(|left, right| left.0.cmp(&right.0)); + serde_json::Value::Object( + entries + .into_iter() + .map(|(key, value)| (key, ordered(value))) + .collect(), + ) + } + serde_json::Value::Array(values) => { + serde_json::Value::Array(values.into_iter().map(ordered).collect()) + } + other => other, + } + } + serde_json::to_vec(&ordered(serde_json::to_value(value)?)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn encoding_and_generator_golden_vectors() { + let random = EventRandom::new(42, 7, Uuid::from_u128(3), 2, b"event-v1", b"rules-v1"); + assert_eq!( + random.key, + [ + 59, 161, 175, 176, 219, 77, 18, 217, 100, 254, 201, 122, 52, 168, 156, 156, 133, + 24, 87, 25, 184, 42, 90, 28, 118, 222, 184, 90, 0, 5, 189, 57 + ] + ); + assert_eq!(random.draw(None, "weather", 0), 4_793_979_539_177_346_272); + assert_eq!( + random.draw(Some(Uuid::from_u128(9)), "damage", 4), + 1_749_970_658_912_152_394 + ); + assert_eq!(random.below(None, "weather", 0, 6).expect("range"), 2); + assert_eq!( + random + .below(None, "weather", 0, (1_u64 << 63) + 1) + .expect("rejected first draw"), + 5_838_915_579_167_874_243 + ); + } + + #[test] + fn named_draws_do_not_depend_on_order_other_targets_or_retries() { + let random = EventRandom::new(42, 7, Uuid::from_u128(3), 2, b"event", b"rules"); + let expected = (0..32) + .map(|index| random.draw(None, "weather", index)) + .collect::>(); + for index in (0..32).rev() { + random.draw(Some(Uuid::from_u128(9)), "cosmetic", index); + random + .below(None, "other", index, (1_u64 << 63) + 1) + .expect("rejections"); + assert_eq!( + random.draw(None, "weather", index), + expected[index as usize] + ); + } + assert_ne!( + random.draw(None, "weather", 0), + random.draw(Some(Uuid::nil()), "weather", 0) + ); + assert_ne!( + random.draw(None, "weather", 0), + random.draw(None, "damage", 0) + ); + assert!(random.below(None, "weather", 0, 0).is_err()); + assert_eq!(random.below(None, "weather", 0, 1).expect("singleton"), 0); + } + + #[test] + fn field_boundaries_and_occurrence_identity_are_unambiguous() { + assert_ne!(derive(&[b"ab", b"c"]), derive(&[b"a", b"bc"])); + let base = EventRandom::new(1, 2, Uuid::from_u128(3), 4, b"event", b"rules"); + for changed in [ + EventRandom::new(2, 2, Uuid::from_u128(3), 4, b"event", b"rules"), + EventRandom::new(1, 3, Uuid::from_u128(3), 4, b"event", b"rules"), + EventRandom::new(1, 2, Uuid::from_u128(4), 4, b"event", b"rules"), + EventRandom::new(1, 2, Uuid::from_u128(3), 5, b"event", b"rules"), + EventRandom::new(1, 2, Uuid::from_u128(3), 4, b"event2", b"rules"), + EventRandom::new(1, 2, Uuid::from_u128(3), 4, b"event", b"rules2"), + ] { + assert_ne!(base, changed); + } + let left = serde_json::json!({"b": {"y": 2, "x": 1}, "a": [2, 1]}); + assert_eq!( + canonical_json(&left).expect("canonical"), + br#"{"a":[2,1],"b":{"x":1,"y":2}}"# + ); + } +} diff --git a/lib_efo/src/lib.rs b/lib_efo/src/lib.rs index 20e53d6..48f09f1 100644 --- a/lib_efo/src/lib.rs +++ b/lib_efo/src/lib.rs @@ -20,6 +20,7 @@ pub mod diff; pub mod entity; pub mod epoch; pub mod epoch_resolution; +pub mod event_rng; pub mod naming; pub mod output; pub mod repository_format; diff --git a/lib_efo/tests/epoch_resolution.rs b/lib_efo/tests/epoch_resolution.rs index 7acd0ca..5130dc5 100644 --- a/lib_efo/tests/epoch_resolution.rs +++ b/lib_efo/tests/epoch_resolution.rs @@ -358,3 +358,33 @@ fn stale_epoch_identity_and_population_overflow_are_rejected() { population.effects[0].stat = StatName::Population; assert!(preview(&initial, &config, &population, Uuid::from_u128(3), 0).is_err()); } + +#[test] +fn event_rng_reads_frozen_inputs_and_compounds_its_identity_only_next_epoch() { + use lib_efo::event_rng::EventRandom; + let mut initial = world(100); + initial.rng_seed = 42; + let config = AdjudicationConfig::embedded().expect("config"); + let original = EventRandom::for_event(&initial, Uuid::from_u128(1), 0, &config).expect("rng"); + let mut unrelated = initial.clone(); + let mut town = unrelated.towns[0].clone(); + town.id = Uuid::from_u128(9); + unrelated.towns.push(town); + assert_eq!( + EventRandom::for_event(&unrelated, Uuid::from_u128(1), 0, &config).expect("rng"), + original + ); + let ruling = + preview(&initial, &config, &spec(2, 30), Uuid::from_u128(1), 0).expect("event as target"); + let mut updated = apply(&initial, &config, &[(EntityType::Event, ruling)]).expect("apply"); + updated.rng_seed = 77; // A metadata edit must not alter already-frozen draws. + assert_eq!( + EventRandom::for_event(&updated, Uuid::from_u128(1), 0, &config).expect("frozen rng"), + original + ); + updated.epoch_id = EpochId::new(1); + assert_ne!( + EventRandom::for_event(&updated, Uuid::from_u128(1), 0, &config).expect("next rng"), + original + ); +}