epoch_forge/docs/deterministic-execution-des...

16 KiB

Deterministic event execution

Status: the serial epoch reducer, persisted baseline, and all three CLI resolution paths are implemented. Actual worker pools remain future work. This extends the resolution design and simulation design. See the implementation checklist.

The first applied resolution after a commit freezes the complete worktree. Further invocations use that baseline until the epoch ID changes on commit or epoch next. Each externally supplied ruling is an independent work item; its effective contribution is its clamped result minus the baseline. Reports are enrolled incrementally, with duplicate application refused. A future worker scheduler must freeze its complete task manifest before dispatch; the current CLI does not automatically discover or generate event tasks.

Guarantee and scope

Given the same initial semantic world, seed, explicit rulings, logical batch, configuration, and versioned rules, execution must produce identical semantic state and canonical reports regardless of worker count, scheduling, partitioning, completion order, or task retries. Wall-clock time and transaction bookkeeping are outside this guarantee and must never feed simulation decisions.

A batch resolves one epoch from an immutable starting snapshot S. Its event manifest is explicit, not whatever happens to fit in a worker queue. Events compound across epochs, never through other events in the same epoch. All tasks in a batch read S, including target stats, source potency, positions, protection, topology, and eligibility. No task reads another task's proposed writes. Statistical dependencies between rulings require the next epoch. A future event evaluator may perform ordered internal steps on its own private copy; the current evaluator treats every supplied ruling independently. Scheduling 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. 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.

Separate occurrence identity from event contents:

occurrence = (source UUID, logical tick/round, phase, occurrence ordinal)
task      = (occurrence, target UUID, effect slot)
key       = H("efo/event-rng/v1", seed, occurrence,
              canonical event-definition hash, rules/config digest)
draw      = RNG(key, target UUID, purpose label, draw index)

Ordinals and effect slots must come from stable input identities, never queue positions or atomic counters. Distinct identical-looking events retain distinct UUIDs. Retrying an occurrence reuses its draws; a later occurrence has different 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. 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 not make generation tasks independently schedulable. Preserve the current same-binary guarantee until a versioned generation algorithm replaces it. Thread-local/fuzzy random helpers must not be reachable from replayable tasks.

Evaluate, reduce, normalize, publish

  1. Validate S and freeze a complete, bounded task manifest, rules, and config. A future worker pool assigns stable batch/task identities before dispatch; current commands identify reports by epoch, source, target, ruling content, and explicit occurrence/tick/round.

  2. Pure workers return proposals and diagnostics. A numeric proposal is an effective signed contribution against S: the event-local normalized result minus the original value. Per-ruling and per-event clamping are allowed inside the isolated event evaluator. Workers perform no repository writes, output, clock reads, or global RNG calls.

  3. Collect exactly one result per expected task. Identical retry results are deduplicated; conflicting duplicates, missing tasks, or any failure abort the batch. Completion order cannot decide which results count.

  4. Group additive proposals by stable target and primitive field identity:

    contribution_i   = normalize(f_i(S))[target, field] - S[target, field]
    D[target, field] = exact_sum(all event contributions for this key)
    raw_after        = S[target, field] + D[target, field]
    after            = normalize(raw_after, target kind, rules)
    

    Add the original value once. A percentage effect computes its delta from S, so two +10% effects on 100 yield 120, not 121. This is simultaneous semantics.

  5. Normalize the combined primitive stats again, then recompute derived stats in a specified dependency order. Initially normalization means the existing OverallStats::clamp_for domains: ordinary population >= 0; event/blocker population >= -120; growth rate in [-120, 120]; other primitive stats in [0, 120], or [-120, 120] for events/blockers. Population has no domain upper cap beyond representation limits. Do not use display-scale conversions.

  6. Reduce nonnumeric state with explicit rules below, validate the complete result, and produce a canonical report. Sort by phase, source, occurrence, target, effect slot, and diagnostic code as applicable, never arrival order.

  7. Under the repository writer lock, verify the entire input snapshot revision and rules/config digest are still current; abort stale work. Publish the world and batch receipt together through existing transaction/recovery mechanisms. The current CLI refuses already-recorded rulings without applying them again. Deliberate repeated direct rulings use --occurrence; future worker-result retries may be deduplicated before publication.

Use fixed-width checked arithmetic and an exact widened accumulator (for example i128 with validated magnitude/task limits proving no intermediate overflow). Reject unsupported ranges deterministically before publication. Never use saturating partial sums: they are not associative with mixed signs. Specify signed division as truncation toward zero and round each scaled effect at a defined step, then sum integers. Preserve the current nested attenuation rounding when compatibility is required. Floating-point parallel reductions are outside this initial contract. Scaling and sums now use i128 intermediates, but persisted isize ranges still limit cross-platform replay; no persisted numeric format is changed by this proposal.

Reports retain each requested/scaled delta, event-local clamped contribution, common before value, aggregate delta, final after value, and normalization adjustment. Do not claim that each event individually achieved its full delta when the total was clamped. There is no unique per-event allocation of clamping loss; defer attribution unless a versioned allocation policy is introduced.

State that cannot simply be summed

Operation Required batch rule
Source potency Minimum of starting potency and all proposed retained potencies; destruction dominates and gives zero.
Destroyed/expired flags Logical OR; no implicit resurrection.
Affected/resolved sets Set union; conflicting values for the same resolution key are an error, not last-writer-wins.
Source audit pointer Select the final record in canonical order, or introduce a batch link; never use completion order.
Conflict lifecycle Compute once after all participant outcomes/removals have been reduced.
Replacement, movement, ownership, deletion Require a versioned conflict policy or reject competing proposals; do not convert arbitrary writes into deltas.
Resource transfers Collect demands, then allocate deterministically against snapshot capacity; preserve both sides of each transfer.
Spawned events/entities Derive IDs from parent occurrence and stable child slot; admit them in the next phase/tick.

For simultaneous resolution, every admitted target uses the source potency from S. Destruction reduces retained source potency to zero for the next epoch and stops that source's own frontier immediately. It does not retroactively cancel other admitted same-epoch contributions. If destruction should prevent another event, that event belongs to a later epoch. Earlier logical arrivals must precede later ones; a multi-tick command cannot collapse dependent ticks into one snapshot.

Define travel/arrival/resolution phase order before integrating simulation commands: e.g. advance travel, freeze arrival positions, propagate diffusion, then resolve supplied rulings. This is a proposed order, not existing behavior. Threshold-triggered follow-up events inspect normalized results in the next epoch; no same-phase feedback loops. Competing transfers cannot merely debit, clamp at zero, and credit in full, because that creates resources.

Comparison with the previous sequential implementation

The previous paths were adjudication::preview_at_potency, apply_to_target, and apply_to_world, plus CLI arrival/conflict orchestration. Diffusion ticks themselves mark arrivals/expiry; they do not apply stat effects.

  • The low-level legacy preview scales chosen/default deltas, mutates a target clone, and calls update_metastats after each effect. Application checks recorded before values and writes absolute after-values. Two previews of the same field from one snapshot cannot safely be applied successively: the second normally fails its stale check. The implemented epoch_resolution API now performs independent preview and aggregate application instead.
  • Previously, separate rulings read the latest world and clamped each time. With health 110, effects +20 then -20 yield 100; reversing them yields 110. Snapshot summation of independently clamped contributions yields 100 in either worker order. At health 5, -10 then +10 yields 10, reversed yields 5, and independent clamping plus snapshot summation yields 10. Thus this proposal is not generally equivalent to sequential adjudication.
  • Fixed additive deltas agree when intermediate clamping/overflow never occurs and target selection, scaling, source state, and other dependencies stay unchanged. Percentage compounding is a hypothetical future effect, not the current explicit signed-delta API.
  • An arrival resolution already previews the town and selected characters against the same snapshot and potency, then applies reports to distinct targets. A conflict round similarly previews distinct participants. These paths now share the epoch reducer, including overlapping targets.
  • Previously, event rulings could reduce source potency before later defaults were calculated. Within the implemented epoch interval they all use initial potency. This is another intentional semantic change. Explicit effects bypass default level and source scaling, but still undergo disposition attenuation and clamping.
  • apply_to_world currently overwrites source state from each report and apply_to_target checks changed target fields, not the complete read set. Those legacy primitives are no longer used by CLI resolution; on their own, a late old report could overwrite stronger attenuation/destruction. Reduce source state and validate the snapshot once instead of reusing the per-report application loop.

Historical records retain their existing interpretation. All resolution commands will adopt the new ruleset using a persisted epoch baseline; see the implementation task list. The 1.1 schema provides old-data defaults, compatibility fixtures, and atomic publication/recovery. Never silently reinterpret old sequential reports as simultaneous contributions.

Mental soundness checks and implementation gates

Scenario Expected result / gap exposed
Permute tasks, worker counts, and reduction trees Identical exact totals, normalized world, IDs, reports, and ordered diagnostics.
Retry one +7 task twice +7 once, not +14; requires manifest identity and deduplication.
Two distinct identical +7 occurrences +14; content hashing alone must not erase an occurrence.
+20/-20 at health 110 100: independently clamped contributions are +10 and -20.
Two -10 demands on a resource balance of 10 Needs allocation; naive clamping cannot conserve paired credits.
Destroy and dampen one source concurrently Source remains destroyed at potency zero; other admitted events still use S.
Target unchanged, blocker/road/source/config edited during evaluation Entire batch is stale; checking written fields alone is insufficient.
A worker fails, or process dies before publication No partial world; journal recovery handles interrupted publication.
Add a target or unrelated random draw Existing named draws stay unchanged when their declared inputs stay unchanged.
Split a dependent ten-tick run into ten one-tick runs Same result only if both execute the same logical phase barriers.
Threshold reached midway through contributions Trigger next epoch after normalization, once, with a stable child identity.
Extreme mixed-sign deltas on different architectures Same result or same validated range error, never wrapping/saturating by schedule.

The proof is conditional but simple: pure evaluation fixes each proposal; deduplication fixes the proposal multiset; exact addition, min, OR, and set union are associative and commutative; deterministic normalization and lifecycle rules fix the final world. Any operation outside those conditions needs an explicit reducer or a phase dependency. A lock alone cannot provide this guarantee.

Before adding threads, turn this table into tests against a serial reference: permutation/partition properties, golden RNG/encoding vectors, legacy-versus-batch boundary fixtures, duplicate/missing/conflicting results, stale-read refusal, limits, crash recovery, and byte-equivalent canonical reports. Then compare real worker-pool runs with deliberately varied scheduling to that same reference. Executable tests now cover ruling-order permutations across all three command families, clamping, source reduction, duplicates, stale snapshots, old data, corruption, limits, stage/restore/revert, and next-epoch compounding. Worker-pool scheduling, transfers, spawned events, and integrated tick phases remain design requirements, not implemented features.