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

214 lines
14 KiB
Markdown

# Deterministic event execution
Status: proposed execution contract, not an implemented worker pool or a change
to existing commands. This extends the [resolution design](resolution-conflict-design.md)
and [simulation design](simulation-worldgen-design.md). 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:
```text
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:
```text
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](epoch-resolution-tasks.md). 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.