diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index edd57f5..aeef52c 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 228b984..7261b92 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/deterministic-execution-design.md b/docs/deterministic-execution-design.md new file mode 100644 index 0000000..4ef5c78 --- /dev/null +++ b/docs/deterministic-execution-design.md @@ -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. diff --git a/docs/resolution-conflict-design.md b/docs/resolution-conflict-design.md index 96151f9..9f0346a 100644 --- a/docs/resolution-conflict-design.md +++ b/docs/resolution-conflict-design.md @@ -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