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

247 lines
16 KiB
Markdown

# 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](resolution-conflict-design.md) and
[simulation design](simulation-worldgen-design.md). See the
[implementation checklist](epoch-resolution-tasks.md).
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:
```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. 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:
```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. 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](epoch-resolution-tasks.md). 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.