74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# 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.
|
|
- [x] Add versioned persisted epoch baseline/record membership with old-data
|
|
defaults and compatibility fixtures before activating the new schema.
|
|
- [x] Implement pure baseline preview and exact reduction of clamped ruling
|
|
contributions; merge source potency by minimum and destruction by OR.
|
|
- [x] Test permutations, bounds, overlapping targets, duplicates, stale edits,
|
|
source state, malformed persisted accumulators, and cross-epoch compounding.
|
|
- [x] Integrate all three CLI resolution paths and show epoch aggregate results
|
|
separately from independent ruling outcomes.
|
|
- [x] Persist resolutions with a full stale-snapshot check under the writer
|
|
lock; integrate staging, restore, revert, historical validation, and format
|
|
compatibility safeguards.
|
|
- [x] Add deterministic event-local named random draws with pinned encoding and
|
|
golden vectors, without introducing RNG into externally adjudicated rulings.
|
|
- [x] 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.
|
|
|
|
Checkpoint 1: pure reducer and six library tests pass. The schema defaults to
|
|
absent on legacy data; ordinary format-1.0 saves explicitly refuse accumulator
|
|
state until transactional format publication is integrated in checkpoint 2.
|
|
|
|
Checkpoint 2: all resolution command families use the reducer; format-1.1
|
|
publication validates the full snapshot under lock. Integration tests exercise
|
|
mixed-command order, staging/restore, compounding, compatibility, locks,
|
|
interrupted transactions, stale input, and revert.
|
|
|
|
Checkpoint 3: immutable event-local ChaCha12 draws use explicit seed/epoch/event/
|
|
occurrence identities and named target/purpose/index keys. Generator and encoding
|
|
versions are pinned; golden vectors were cross-checked with an independent
|
|
Python FNV/ChaCha12 reference calculation. GM rulings and existing worldgen do
|
|
not call this API. No worker pool, transfer allocation, or automatic event
|
|
scheduling is introduced by this feature.
|
|
|
|
Final validation: formatting, 167 locked all-feature workspace tests, and strict
|
|
Clippy pass. All implementation increments are committed on the feature branch.
|