247 lines
16 KiB
Markdown
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.
|