docs: define deterministic event execution rules
This commit is contained in:
parent
88d3fc4695
commit
7d61806c5b
|
|
@ -258,6 +258,24 @@ and [`docs/presentation-design.md`](docs/presentation-design.md).
|
|||
destroyed no-op effects, clamping, stale/repeated application, CLI audit,
|
||||
aliasing, and worktree restoration.
|
||||
|
||||
### Deterministic execution design
|
||||
|
||||
- [x] Document immutable batch inputs, event/occurrence RNG identities, exact
|
||||
delta reduction, normalization, retries, phase barriers, and atomic publication
|
||||
in `docs/deterministic-execution-design.md`.
|
||||
- [x] Compare current adjudication/diffusion/conflict code with simultaneous
|
||||
semantics and mentally check schedule independence and failure cases.
|
||||
- Decision: simultaneous clamping and snapshot source potency are new ruleset
|
||||
semantics, not a behavior-preserving parallelization of sequential commands.
|
||||
- Discovery: current per-report absolute after-values, source-state overwrites,
|
||||
sequential worldgen RNG, and platform-sized arithmetic need dedicated work.
|
||||
- Validation: formatting, all-target/all-feature locked workspace tests, and
|
||||
strict Clippy passed; this change documents rules without changing runtime behavior.
|
||||
- [ ] Implement a versioned serial batch reference and proposal/receipt schema
|
||||
with compatibility fixtures before introducing a worker pool.
|
||||
- [ ] Convert mental checks into executable permutation, retry, stale-state,
|
||||
arithmetic, RNG golden-vector, and recovery tests.
|
||||
|
||||
### Presentation completion (#10)
|
||||
|
||||
- [x] Approve the remaining renderer/export contract in
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ behavior clearly.
|
|||
fuzzing, roads, movement, diffusion, map rendering, and config packaging.
|
||||
- [Adjudication/influx, diffusion resolution, and conflict](resolution-conflict-design.md):
|
||||
implementation contract for tracker issues #9, #8, and #12.
|
||||
- [Deterministic execution](deterministic-execution-design.md): proposed snapshot
|
||||
batches, independent RNG, reduction rules, compatibility analysis, and mental checks.
|
||||
- [Presentation and export](presentation-design.md): remaining buffered,
|
||||
coherent, saveable output contract for tracker issue #10.
|
||||
- [Roadmap](roadmap.md): current work and stretch proposals.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,209 @@
|
|||
# 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 is an explicit simultaneous tick/round/phase with an immutable input
|
||||
snapshot S. It is not whatever work happens to fit in a worker queue. Separate
|
||||
user commands remain sequential. 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 require another phase and a
|
||||
barrier; only ready tasks within a phase may run in any order.
|
||||
|
||||
## 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
|
||||
**unclamped signed delta** against S, not an absolute after-value or a delta
|
||||
reconstructed from a clamped preview. 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
|
||||
D[target, field] = exact_sum(all proposed deltas 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 primitive stats once, then recompute derived stats once 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 contribution, the 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 stops future phases; it does not retroactively cancel sibling
|
||||
tasks in the same batch. If destruction should prevent another arrival, those
|
||||
arrivals need ordered phases. 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 at the next
|
||||
barrier; 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
|
||||
yields 110 in either worker order. At health 5, -10 then +10 yields 10,
|
||||
reversed yields 5, and snapshot summation yields 5. 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.
|
||||
|
||||
Keep existing sequential commands and historical records interpretable under
|
||||
their existing rules. Introduce simultaneous batches under a new ruleset ID,
|
||||
with explicit boundaries and previews. Before storing batch receipts/proposals,
|
||||
design the schema version, old-data defaults, fixtures, and recovery behavior.
|
||||
Never silently reinterpret old reports as unclamped 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 | 110; catches premature clamping and confirms changed sequential semantics. |
|
||||
| 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; admitted siblings 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 only 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.
|
||||
|
|
@ -10,6 +10,11 @@ appearing in this document.
|
|||
|
||||
## Product contract
|
||||
|
||||
Future simultaneous execution is specified in the
|
||||
[deterministic execution proposal](deterministic-execution-design.md), including
|
||||
snapshot reads, event-local RNG, delta reduction, and differences from current
|
||||
sequential clamping and source attenuation. It does not change existing commands.
|
||||
|
||||
An **adjudication** (formerly called an “influx”) is a player-made roll outside
|
||||
Epoch Forge. The game master interprets that result, chooses its level,
|
||||
disposition, targets, and exact effects, then uses Epoch Forge to preview and
|
||||
|
|
|
|||
Loading…
Reference in New Issue