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

14 KiB

Deterministic event execution

Status: proposed execution contract, not an implemented worker pool or a change to existing commands. This extends the resolution design and simulation design. Implement the serial reference evaluator first; parallel evaluation must produce the same result.

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. Dependencies between events require the next epoch. An event may perform ordered internal steps on its own private copy, with clamping after each ruling. Workers schedule whole events independently.

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

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.

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. Assign stable batch and task identities before dispatch.

  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. A retry of a published batch returns its receipt without applying effects again. New intentional execution requires a new batch ID.

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. Current isize values and saturating scale multiplication need a portability/range audit before cross-platform replay is promised; 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 becomes visible to other events next epoch; it does not retroactively cancel sibling tasks in the same batch. 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 current event handling

The relevant existing paths are 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.

  • A 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. A batch reducer needs a new proposal API.
  • Separate rulings read the latest world and clamp 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 are useful foundations, but do not establish overlapping-event reduction.
  • Separate event rulings can reduce source potency before later defaults are calculated. Within the proposed batch 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. That is insufficient for arbitrary parallel reports: 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. Before storing batch receipts/proposals, design the schema version, old-data defaults, fixtures, and recovery behavior. 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. This document's mental checks are design analysis, not passing executable tests.