docs: plan simultaneous epoch resolution rollout

This commit is contained in:
Dandaedre 2026-09-24 19:13:06 +02:00
parent 7d61806c5b
commit 1ebba7b75b
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 87 additions and 24 deletions

View File

@ -260,6 +260,11 @@ and [`docs/presentation-design.md`](docs/presentation-design.md).
### Deterministic execution design
- Active implementation: [epoch resolution task list](docs/epoch-resolution-tasks.md).
- Updated decision: all resolution commands share a persisted epoch baseline;
clamp each independent ruling, sum its effective contribution, clamp the total.
Commit/epoch-next is the compounding boundary.
- [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`.

View File

@ -13,12 +13,13 @@ 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
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 require another phase and a
barrier; only ready tasks within a phase may run in any order.
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
@ -64,8 +65,9 @@ Thread-local/fuzzy random helpers must not be reachable from replayable tasks.
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,
**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
@ -73,14 +75,15 @@ Thread-local/fuzzy random helpers must not be reachable from replayable tasks.
4. Group additive proposals by stable target and primitive field identity:
```text
D[target, field] = exact_sum(all proposed deltas for this key)
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 primitive stats once, then recompute derived stats once in a
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
@ -106,7 +109,7 @@ 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,
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
@ -126,16 +129,16 @@ unless a versioned allocation policy is introduced.
| 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;
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 at the next
barrier; no same-phase feedback loops. Competing transfers cannot merely debit,
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
@ -151,8 +154,9 @@ Diffusion ticks themselves mark arrivals/expiry; they do not apply stat effects.
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
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
@ -172,11 +176,11 @@ Diffusion ticks themselves mark arrivals/expiry; they do not apply stat effects.
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,
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 reports as unclamped contributions.
Never silently reinterpret old sequential reports as simultaneous contributions.
## Mental soundness checks and implementation gates
@ -185,14 +189,14 @@ Never silently reinterpret old reports as unclamped contributions.
| 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. |
| +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; admitted siblings still use S. |
| 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 only after normalization, once, with a stable child identity. |
| 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;

View File

@ -0,0 +1,54 @@
# Epoch resolution implementation plan
Scope: all existing adjudication, diffusion-arrival, and conflict-round commands
adopt simultaneous epoch statistics. Actual worker pools and automated GM rolls
are out of scope. This is a cross-cutting library/persistence/CLI change, not
merely moving a clamp: independent CLI invocations need durable common inputs.
The first resolution after a commit freezes the worktree as the epoch baseline.
Every ruling reads its target and source potency from that baseline. Its local
result is clamped; its contribution is `local_after - baseline`. Contributions
are summed exactly, added to the baseline once, then clamped again. A commit
ends the accumulation interval. `epoch next` also commits, so compounds normally.
Repeated conflict rounds within that interval use the same statistical baseline;
round lifecycle and explicit diffusion arrival bookkeeping remain ordered.
## Incremental commits
- [x] Create `feat/deterministic-epoch-resolution`; revise the execution contract
and record this assessment and task list.
- [ ] Add versioned persisted epoch baseline/record membership with old-data
defaults and compatibility fixtures before activating the new schema.
- [ ] Implement pure baseline preview and exact reduction of clamped ruling
contributions; merge source potency by minimum and destruction by OR.
- [ ] Test permutations, bounds, overlapping targets, duplicates, stale edits,
source state, malformed persisted accumulators, and cross-epoch compounding.
- [ ] Integrate all three CLI resolution paths and show epoch aggregate results
separately from independent ruling outcomes.
- [ ] Persist resolutions with a full stale-snapshot check under the writer
lock; integrate staging, restore, revert, historical validation, and format
compatibility safeguards.
- [ ] Add deterministic event-local named random draws with pinned encoding and
golden vectors, without introducing RNG into externally adjudicated rulings.
- [ ] Update command/help/repository documentation and CLI workflow tests; run
formatting, locked all-feature workspace tests, and strict Clippy before each
implementation commit.
## Design decisions and risks
- Older binaries must refuse repositories after the new accumulator is written;
silently dropping it would reintroduce compounding. Use a minor format bump
and atomic manifest/worktree publication on the first new-format write.
- Old records remain sequential audit entries. Only explicitly enrolled records
contribute to the active accumulator; never infer membership from timestamps.
- Manual edits to a contributing field require an epoch boundary or restoring
the resolution. A stale proposal must not overwrite them.
- Exact integer reduction is necessary: saturation during summation is dependent
on order. Retain current stat domains and validate representation limits.
- Source exhaustion cannot cancel already admitted simultaneous effects. Source
potency used by subsequent rulings stays at the epoch baseline.
- Membership and baseline increase snapshot size. Keep only the current interval's
baseline, without recursively embedding earlier accumulators; committed epochs
preserve earlier baselines and audit history.
- Event-local RNG is a foundation API; worldgen's existing sequential stream is
a separate versioned generator and remains unchanged in this feature.