docs: plan simultaneous epoch resolution rollout
This commit is contained in:
parent
7d61806c5b
commit
1ebba7b75b
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue