feat: add reproducible named event random draws
This commit is contained in:
parent
4eb42159ec
commit
4124e9c61d
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -652,6 +652,7 @@ dependencies = [
|
|||
"miette",
|
||||
"once_cell",
|
||||
"rand",
|
||||
"rand_chacha",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"tempfile",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
||||
|
|
|
|||
|
|
@ -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}}"#
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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
|
||||
);
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue