epoch_forge/docs/epoch-resolution-tasks.md

3.3 KiB

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

  • 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.