epoch_forge/docs/epoch-resolution-tasks.md

59 lines
3.5 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.
- [ ] 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.
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.