feat: add reproducible named event random draws

This commit is contained in:
Dandaedre 2026-09-24 19:32:02 +02:00
parent 4eb42159ec
commit 4124e9c61d
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
8 changed files with 322 additions and 7 deletions

View File

@ -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)

1
Cargo.lock generated
View File

@ -652,6 +652,7 @@ dependencies = [
"miette",
"once_cell",
"rand",
"rand_chacha",
"serde",
"serde_json",
"tempfile",

View File

@ -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

View File

@ -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.

View File

@ -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"

256
lib_efo/src/event_rng.rs Normal file
View File

@ -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<Self, EventRandomError> {
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<Uuid>, 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<Uuid>,
purpose: &str,
index: u64,
upper: u64,
) -> Result<u64, EventRandomError> {
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<Uuid>, 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<Vec<u8>, 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::<Vec<_>>();
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::<Vec<_>>();
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}}"#
);
}
}

View File

@ -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;

View File

@ -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
);
}