docs: prepare tracker simulation and output work

This commit is contained in:
Dandaedre 2026-09-22 01:46:15 +02:00
parent 70123bf0d5
commit 4bf484a96e
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
9 changed files with 532 additions and 18 deletions

View File

@ -44,8 +44,8 @@ tests open it as a real repository and validate its map and world invariants.
**History semantics checkpoint: complete.** `revert` now defaults to a
reviewable worktree inverse, `revert --commit` warns before adding history, and
`reset --hard` provides a previewed, explicitly confirmed destructive rewind.
Recoverable future pruning remains the recommended alternative and rewinds the
next epoch to `HEAD + 1`, with allocator and tags included in its backup.
Recoverable future pruning remains the recommended alternative and never
reuses removed epoch IDs; allocator and tags are included in its backup.
**Tracker checkpoint — inspection and audit: complete.** Gitea issues #18 and
#19 are addressed by unified filtered entity/epoch inspection, and #14 now
@ -57,6 +57,12 @@ mapped to implemented, partial, blocked, and planned work in
enforced policy across CLI edits, TUI drafts, derived-stat recalculation, and
workspace validation without clamping real population counts.
**Tracker prework — issues #9, #8, #10, and #12: complete.** The shared
deterministic resolution, diffusion-outcome, generic conflict, presentation,
export, persistence, CLI, safety, and test contracts are implementation-ready
in [`docs/resolution-conflict-design.md`](docs/resolution-conflict-design.md)
and [`docs/presentation-design.md`](docs/presentation-design.md).
## Phase 0 — audit and guardrails
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
@ -216,6 +222,49 @@ workspace validation without clamping real population counts.
- [x] Test repeated application, convergence, expiry, disconnected graphs, and
deterministic replay across many seeds.
### Checkpoint 3.5 — tracker simulation resolution (#9, #8, #12)
- [x] Approve the shared prework contract in
`docs/resolution-conflict-design.md`.
- [ ] Add a separately versioned, embedded `SimulationConfig` with strict
validation, external replacement, safety limits, and release packaging.
- [ ] Implement all six stable `InfluxLevel` values, configured pressure bands,
deterministic target sub-seeds, resistance, attenuation, and typed reports.
- [ ] Persist idempotent, stale-state-checked resolution records with workspace
and historical `fsck` validation.
- [ ] Add preview/apply/show/clear influx commands plus the documented `roll`
compatibility alias and complete help examples.
- [ ] Resolve diffusion arrivals against protected towns and configured
blockers, explaining avoided/dampened/destroyed outcomes.
- [ ] Resolve resident and positioned characters deterministically; document
the initial policy for characters currently in transit.
- [ ] Add generic multi-side conflict records, participant validation, pure
fight/war round resolution, victory, stalemate, and explicit ending.
- [ ] Add conflict commands and focused fight/war aliases with preview-first,
worktree-only application and restore/stage/commit/revert coverage.
- [ ] Cover every influx boundary and outcome, shuffled insertion order,
replay, repeated application, stale state, corruption, allocation limits,
multi-side conflict, and diffusion/conflict integration.
### Presentation completion (#10)
- [x] Approve the remaining renderer/export contract in
`docs/presentation-design.md` and inventory production direct output.
- [ ] Add shared output options, semantic document blocks, a single process
sink, and an atomic non-overwriting output-file writer.
- [ ] Migrate destructive/safety and simulation previews to typed reports and
buffered human/plain/JSON rendering.
- [ ] Migrate state/history, entity, and generation output without changing
domain behavior.
- [ ] Remove production printing from `lib_efo`; retain strings or writer-based
compatibility APIs only where necessary.
- [ ] Add a source-policy check preventing new production print macros outside
the output sink and entry error boundary.
- [ ] Test colour/portable/redirection behavior, stable JSON schemas, output
collisions, permission failures, atomicity, large lists, and help examples.
- Raw audit baseline: 122 print-macro call sites across 15 source files;
comments and test-only calls will be excluded when enforcing the final gate.
### Checkpoint 4 — PNG map rendering
- [ ] Store optional base-map path and coordinate bounds without embedding

View File

@ -13,6 +13,10 @@ behavior clearly.
and accessibility contract.
- [Simulation and world generation](simulation-worldgen-design.md): seeded
fuzzing, roads, movement, diffusion, map rendering, and config packaging.
- [Influx, diffusion resolution, and conflict](resolution-conflict-design.md):
implementation contract for tracker issues #9, #8, and #12.
- [Presentation and export](presentation-design.md): remaining buffered,
coherent, saveable output contract for tracker issue #10.
- [Roadmap](roadmap.md): current work and stretch proposals.
- [Gitea issue audit](issue-audit.md): disposition and dependencies of the
upstream tracker backlog.

View File

@ -2,7 +2,7 @@
This audit maps the open issues from the
[project tracker](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues)
to the current codebase as of 2026-09-21. Tracker entries predate several
to the current codebase as of 2026-09-22. Tracker entries predate several
milestones, so an open checkbox does not necessarily mean the behavior is
absent.
@ -15,12 +15,13 @@ absent.
| [#15 Clamp stats](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/15) | Addressed: CLI/TUI mutations clamp normalized persistent stats to `0..=120`, event/blocker modifiers and growth to `-120..=120`, and population remains an unbounded non-negative count (or a bounded negative modifier). Workspace validation rejects bypassed invalid state. | Move these defaults into schemas if custom-stat domains become configurable. |
| [#14 Build fsck](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/14) | Addressed for read-only validation: every epoch is parsed and checked for duplicate IDs, collection types, ordinary links, governors, and capitals. | Put serializer rewriting in a separately previewed repair command, not `fsck`. |
| [#13 Add all cards into pre-events](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/13) | Explicitly deferred by the maintainer for this milestone. | Revisit only when requested. |
| [#12 Add fight/war](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/12) | Open simulation feature. | Model it as configured events/relationships after custom fields and influx semantics settle. |
| [#12 Add fight/war](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/12) | Not implemented. The implementation-ready design uses generic multi-side conflict records and reuses deterministic influx resolution. | Deliver after the influx engine and diffusion integration; see `resolution-conflict-design.md`. |
| [#11 Epoch Diffing](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/11) | Addressed: epoch and layer comparisons share a deterministic, serializable typed diff with changed-field details and importance classification. | Extend the type rather than parsing terminal output when structured formats arrive. |
| [#10 Display functions](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10) | Addressed for inspection: unified `show` and diff rendering build complete strings before a single output write, and `Displayable::full_display` no longer forces library output through `println!`. | Apply the same boundary opportunistically to mutation confirmations. |
| [#9 Adding influx](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9) | Open and underspecified. | Define versioned deterministic severity and avoidance rules before commands. |
| [#8 Event diffusion](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/8) | Addressed: events have persisted origins, deterministic road/direct frontiers, affected sets, expiry, previewed ticks, replay tests, and worktree-only application. | Extend effects through configurable influx rules rather than embedding setting assumptions. |
| [#10 Display functions](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10) | Partially addressed: unified `show`, entity detail, and diff rendering are buffered. Most commands and several legacy library helpers still print directly; saving/structured output is absent. | Implement the renderer/sink migration and acceptance inventory in `presentation-design.md`. |
| [#9 Adding influx](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9) | Not implemented. All six levels, deterministic rolls, avoidance/destruction, attenuation, configuration, records, CLI, and tests now have an approved prework contract. | Implement slices 1–3 of `resolution-conflict-design.md`. |
| [#8 Event diffusion](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/8) | Partially addressed: deterministic road/direct town frontiers, affected sets, expiry, previewed ticks, and reversible application exist. Influx-aware outcomes, protected-town avoidance, and character targeting remain. | Integrate the shared resolution engine using the explicit #8 acceptance gates in `resolution-conflict-design.md`. |
| [#6 HashMap/HashSet](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/6) | Addressed without format churn: `EntityIndex` provides ephemeral UUID/name hash indexes and duplicate-ID detection over the stable vector representation. Repository validation uses the index and hash lookup for relationships. | Rebuild indexes after mutation; never persist them. |
Roads and residency now provide the shared spatial foundation. Next build
influx, fight/war, and diffusion on it; issue #13 remains explicitly deferred.
Implementation order is #9's shared resolution engine, the remaining #8
outcomes, then #12 conflicts. #10 presentation work accompanies each slice and
finishes with a complete direct-output migration. Issue #13 remains deferred.

163
docs/presentation-design.md Normal file
View File

@ -0,0 +1,163 @@
# Presentation and export design
This is the remaining implementation contract for tracker issue
[#10](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10).
`show`, full entity display, and world diff already build strings before the
CLI writes them. The issue is not complete until every command follows one
coherent output boundary and useful reports can be saved without scraping ANSI
terminal output.
## Goals
- Domain/library operations return typed data and never print.
- Command handlers resolve input and choose presentation; renderers never
mutate repositories.
- Each invocation performs at most one stdout write and, when needed, one
stderr write after successful rendering.
- Essential meaning survives `NO_COLOR`, `--no-default-features`, redirection,
narrow terminals, and UTF-8 terminals without Nerd Fonts.
- The same typed report can target terminal text, plain text, or a stable
machine representation without parsing a decorated string.
- `--output PATH` writes atomically and refuses to overwrite unless explicitly
requested. It never changes repository state.
## Layering
```text
lib_efo domain operation
↓ typed result/report
bin_efo presentation model
↓ renderer selected by OutputOptions
String / serializable value
↓ one stdout write or atomic output-file replacement
```
Introduce a small `presentation` module in `bin_efo`; do not make `lib_efo`
depend on terminal crates.
```text
OutputOptions {
format: Human | Plain | Json,
output: Option<PathBuf>,
force: bool,
color: Auto | Always | Never
}
Document {
title: Option<String>,
blocks: Vec<Block>
}
Block = Paragraph | KeyValues | Table | Tree | Changes | Warning | Recovery
```
The document model carries semantics (added/removed/warning/success), not ANSI
codes or Nerd Font glyphs. Human rendering may choose colour and decorative
glyphs; plain rendering uses accessible ASCII/Unicode labels; JSON serializes
the original typed report rather than the human `Document` where possible.
JSON is included here because “printing or saving depending on need” requires
a non-lossy format. Its schema is versioned per report (`schema_version`,
`kind`) and tested. JSON output disables colour and decorative glyphs and emits
no success prose. JSONL remains a later extension for streaming lists.
## CLI contract
Global or consistently flattened options:
```text
--format human|plain|json
--output PATH
--force
--color auto|always|never
```
Defaults preserve today's human terminal experience. When stdout is not a TTY,
`human` automatically suppresses colour but keeps UTF-8 structure. `plain`
avoids decorative icons and ANSI regardless of terminal. Existing
`NO_COLOR` remains honored and wins over `auto`; `--color always` is the only
explicit override.
Writing rules:
- render fully before opening the output path;
- reject repository control paths and an input path used by the command;
- use sibling temporary file, flush, sync when repository-grade durability is
needed, then rename;
- without `--force`, an existing target is an actionable error;
- success/recovery messages go to stderr only when structured output occupies
stdout, otherwise remain part of the human document;
- errors never create or truncate the output file.
## Migration inventory
Priority is determined by risk and reuse, not file order:
1. Safety/destructive previews: `reset`, `prune-future`, recovery, locks.
2. Simulation previews: generation, travel, diffusion, influx, conflict.
3. State/history: status, stage/restore/commit/log/switch/revert, epoch.
4. Entity mutation confirmations and generated-name commands.
5. Legacy library printing (`Displayable::print_full`, `Prettiable` print
helpers, old epoch config helpers) replaced with returned strings or writers.
Tests and debug-only `println!` calls are outside the production inventory.
After migration, CI runs a source check that rejects production
`print!/println!/eprint!/eprintln!` outside the single output sink and process
entry error boundary.
## Information loading
Renderers receive a `ViewContext` assembled once per command:
```text
ViewContext {
repository_summary,
selected_layer,
entity_index,
optional_epoch_metadata,
terminal_capabilities
}
```
This avoids renderers reopening the repository or repeatedly scanning vectors.
It also satisfies the issue's “load many info” goal: entity tables can resolve
links/names, simulation reports can name sources and targets, and historical
views can attach epoch metadata without domain objects performing I/O.
## Coherence rules
- Titles use sentence case; stable IDs always retain an `@` prefix.
- Added/removed/modified markers remain `+`, `-`, `~`; `!` means important.
- Counts and empty states are always explicit.
- Preview documents start with `Preview` and finish with exactly what will or
will not change plus the recovery command.
- Successful mutation documents state the layer changed (`worktree`, `index`,
or committed epoch) and the next useful command.
- Warnings and errors never rely on colour or glyph shape.
- Tables have deterministic column order and rows have stable sort keys.
- Human wrapping is Unicode-width-aware; machine formats never wrap.
## Acceptance gates
- every production command returns/render-writes through one output sink;
- no library production function prints;
- golden tests cover human, portable/plain, and JSON for each report family;
- redirected output contains no ANSI escapes;
- `NO_COLOR` and portable builds retain all semantic labels;
- `--output` success, collision, permission failure, and atomicity are tested;
- JSON schemas round-trip and do not contain rendered terminal strings;
- large lists are bounded or paginated without partial writes;
- display tests use returned buffers, not global stdout capture;
- help documents formats, output files, overwrite behavior, and examples;
- both existing CLI behavior and new simulation previews migrate before #10 is
closed.
## Delivery slices
1. Add `OutputOptions`, the single sink, atomic file writer, and renderer tests.
2. Move safety and simulation previews to typed reports/documents.
3. Move state/history commands and expose plain/JSON formats.
4. Move entity and generation commands; retire production library printing.
5. Add the source-policy check, output-path failure tests, docs, and help
snapshots; close #10 only when the production inventory is empty.

View File

@ -39,8 +39,8 @@ places an inverse change in the worktree by default; `--commit` explicitly
creates a new inverse commit and warns before doing so. `efo prune-future`
previews later epochs and, with confirmation, moves them into a restorable
backup rather than deleting them. Pruning removes future-pointing tags and
rewinds the allocator to `HEAD + 1`; its backup records both so restoration
reconstructs the original timeline metadata.
preserves the monotonic allocator; its backup records both so restoration
reconstructs the original timeline metadata without reusing removed IDs.
`efo reset --hard TARGET --yes` is the exceptional destructive path. It resets
HEAD, index, and worktree, permanently deletes all newer epoch directories,

View File

@ -0,0 +1,290 @@
# Influx, diffusion resolution, and conflict design
This is the implementation contract for tracker issues
[#9](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9),
[#8](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/8), and
[#12](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/12).
It distinguishes the spatial propagation already implemented from the outcome
resolution still required. No command described here is implemented merely by
appearing in this document.
## Product contract
Simulation is deterministic, inspectable, and subordinate to the Git-like
workflow:
- preview is the default and never writes;
- `--apply` changes only the complete worktree snapshot under the repository
writer lock;
- staging and committing remain explicit separate operations;
- previews state the seed, inputs, rule source, selected targets, decisions,
and exact projected changes;
- replaying the same state, configuration, command, and seed produces the same
report and semantic world;
- applying an already-recorded resolution is idempotent;
- users can discard applied work with `efo restore --worktree --all`, or retain
it through `stage` and `commit`;
- simulation never deletes an entity merely because a roll failed. A
`Destroyed` outcome marks the simulation record/event complete and previews
any proposed entity deletion as a separate explicit operation.
The model remains setting-agnostic. “War”, “plague”, “merger”, “strike”, and
“market shock” are labels/configurations over the same participant, pressure,
resistance, and effect primitives. Fantasy-specific unit classes or damage
types do not belong in the core.
## Shared deterministic resolution engine
### Influx levels
`InfluxLevel` is a stable serialized enum and a Clap value enum:
| Level | Default pressure band | Intent |
|---|---:|---|
| `excellent` | +80..+120 | exceptional beneficial effect |
| `good` | +35..+79 | beneficial effect |
| `mid` | -20..+34 | weak or mixed effect |
| `bad` | -55..-21 | harmful effect |
| `worsen` | -90..-56 | strongly harmful/escalating effect |
| `apocalypse` | -120..-91 | extreme harmful effect |
The names are compatibility vocabulary from the issue, not hard-coded story
meaning. Configuration owns the exact inclusive bands. Negative and positive
levels use the same algorithm; polarity only changes the proposed statistic
deltas. Parsed aliases may include `medium` for `mid` and `worse` for
`worsen`, while serialized values remain canonical.
### Inputs and stable records
The library owns serializable types; CLI code only resolves selectors and
renders reports:
```text
InfluxSpec {
level, seed, source_event, ruleset_id,
target_scope, repeat_policy
}
ResolutionRecord {
id, source, target, tick_or_round, seed,
pressure, resistance, outcome, attenuation,
proposed_changes, applied, ruleset_id
}
ResolutionOutcome = Affected | Dampened | Avoided | Destroyed
```
Records use stable UUIDs and are ordered by `(tick_or_round, source, target,
id)`. The RNG is `StdRng::seed_from_u64`; each target derives a sub-seed from
the command seed plus stable source/target IDs, so adding an unrelated target
does not perturb existing results. Rust's randomized hash iteration must never
influence a roll.
`proposed_changes` is a typed list of field/stat deltas, not formatted text.
Every change carries before/projected-after values and the clamping policy.
Application verifies the target still has the recorded before value; stale
state aborts the whole transaction with recovery guidance.
### Pressure, resistance, and attenuation
The first ruleset is deliberately simple and configurable:
1. Select a pressure value from the level's configured band.
2. Add source-stat contributions configured by stat name and weight.
3. Calculate target resistance from configured stats, blockers, and explicit
protection relationships.
4. Add a deterministic bounded roll.
5. Compare `pressure - resistance` against configured thresholds:
`Destroyed`, `Avoided`, `Dampened`, or `Affected`.
6. Multiply configured effects by the resulting attenuation and clamp through
the existing stat-domain policy.
No hidden global randomness or wall-clock time enters the calculation.
Missing optional stats contribute zero and appear in the explanation. Invalid
stat names, unordered ranges, non-finite weights, excessive target counts, or
unknown ruleset versions fail before a preview is produced.
Interpretation of `Destroyed` depends on the source:
- for an incoming event, propagation stops and the event is marked exhausted;
- for a conflict participant, it means removed from that conflict, not deleted
from the repository;
- for a target, entity deletion is never implicit.
`Dampened` writes an attenuation mark to the event/conflict state. Later
resolution uses that mark; it does not repeatedly edit the source's base stats.
### Configuration
Add `lib_efo/assets/simulation/default.json` and a versioned
`SimulationConfig` independent of repository and worldgen versions. It owns:
- the six influx bands and aliases;
- pressure/resistance stat weights;
- outcome thresholds and attenuation ratios;
- effects by target entity type;
- blocker/protection behavior;
- conflict round limits, stalemate rules, and default victory thresholds;
- allocation limits for targets, participants, records, and rounds.
The binary embeds canonical offline defaults and accepts `--config PATH`.
External config is a complete replacement, not a partially merged surprise.
Errors identify the file and JSON field. Release packaging should add this file
beside the existing worldgen configuration.
## Issue #9: influx and roll surface
Proposed CLI:
```text
efo influx preview EVENT --level bad [--target SELECTOR ...] [--seed N]
efo influx apply EVENT --level bad [--target SELECTOR ...] [--seed N]
efo influx show EVENT
efo influx clear EVENT [--yes]
efo roll influx EVENT --level bad ... # visible compatibility alias
```
`preview` and `apply` are intentionally separate words; `apply` still prints
the complete preview before its success line. If no seed is supplied, preview
prints a generated seed that can be copied into `apply`; it must not imply that
a second seed will reproduce the first preview unless supplied explicitly.
Target scopes support stable entity selectors and semantic groups (`towns`,
`characters`, `organisations`, `reached`) without requiring custom fields.
Ambiguous names abort. `reached` consumes the affected set of an event's
diffusion state.
Acceptance gates:
- all six levels parse, serialize, appear in help, and reach their configured
bands at boundary tests;
- the same seed/config/state yields byte-equivalent typed reports;
- avoidance, damping, destruction, and ordinary effect outcomes are covered;
- records prevent accidental reapplication and stale application is atomic;
- invalid config and excessive scope fail before allocation/mutation;
- preview leaves repository bytes unchanged; apply is restoreable;
- source attenuation persists without corrupting source entity statistics.
## Issue #8: finish diffusion resolution
The existing `DiffusionState` already stores origin, elapsed ticks, expiry,
ordered town frontier, affected towns, and road/direct route reasons. Preserve
that representation and extend it additively with:
```text
resolved: BTreeMap<TargetRef, ResolutionId>
stopped: Option<StopReason>
character_policy: Residents | Positioned | Both | None
influx: Option<InfluxSpec>
```
When a tick reaches a town:
1. derive town and character targets according to `character_policy`;
2. inspect blockers/protection before rolling;
3. resolve each stable target through the influx engine;
4. record `Avoided` targets as resolved, preventing repeated rolls;
5. stop the event if its resolution is `Destroyed`;
6. include route, protection source, roll explanation, and projected effects in
the tick report.
Protection is explicit and generic. The first implementation treats positioned
`Blocker` entities and typed links selected by configuration as resistance
contributors. A protected town is not silently omitted: the report says which
blocker/link contributed and whether the result was avoided or dampened.
Characters are resolved in stable UUID order. Residents use mobility state;
positioned characters use exact position/town association; travellers are only
targeted when the configured policy includes their current segment/location.
The initial slice may conservatively exclude in-transit characters until
interpolated travel positions exist, but help and reports must say so.
Acceptance gates add tests for protected and unprotected towns, resident and
roaming characters, destroyed propagation, expiry before arrival, zero-tick
replay, large tick convergence, and deterministic output under shuffled vector
insertion order.
## Issue #12: fight and war
Conflict reuses resolution records instead of directly coupling entities.
```text
ConflictState {
id, name, kind, sides, seed, round, status,
location, ruleset_id, objectives, records
}
ConflictKind = Fight | War
ConflictStatus = Planned | Active | Stalemate | Won { side } | Ended
ParticipantRef { entity_type, id, side, committed_weight }
```
Any stored entity type may participate. Duplicate participants, empty sides,
missing IDs, zero committed weight, and fewer than two sides are invalid.
Side labels are user strings so organisations, coalitions, departments, or
individuals fit the same model.
A fight is a bounded, normally single-resolution conflict. A war is persistent
and advances in explicit rounds. Neither automatically creates/deletes normal
entities. Resolution may propose stat changes and may generate ordinary Event
entities through configuration; these appear in the worktree diff like other
changes.
Proposed CLI:
```text
efo conflict start NAME --kind fight --side red:town:Haven --side blue:org:Guild --seed N
efo conflict preview CONFLICT [--rounds N]
efo conflict advance CONFLICT [--rounds N] --apply
efo conflict show CONFLICT
efo conflict end CONFLICT --reason TEXT [--apply]
efo fight ... # focused alias/help surface
efo war ... # focused alias/help surface
```
Starting and ending are preview-first worktree changes. Advancing resolves all
sides in stable order, snapshots participant inputs for stale-state detection,
and produces typed round reports. Victory and stalemate come solely from the
versioned ruleset. A command cannot advance an ended conflict or silently
re-roll an already recorded round.
Acceptance gates cover two and three-sided conflicts, mixed entity types,
fight completion, multi-round war, victory/stalemate, participant removal,
seed replay, insertion-order independence, clamping, stale-state refusal,
restore/stage/commit/revert, and malformed persisted conflict state.
## Persistence and compatibility
Additive state belongs in `EpochInfo` with `#[serde(default)]`, as roads,
mobility, and diffusion already do:
```text
resolution_records: BTreeMap<Uuid, ResolutionRecord>
conflicts: BTreeMap<Uuid, ConflictState>
```
Never persist RNG objects, hash maps with unstable iteration, display strings,
or pathfinder caches. Workspace validation checks all cross-references,
record uniqueness, monotonic conflict rounds, resolved-target links, ruleset
IDs, and configured safety limits. `fsck` exercises the same validation for
every historical epoch.
These additions remain backward-readable through defaults while the project is
unreleased. Freeze the exact format before the first release; after that point,
any semantic reinterpretation requires a 1.x migration fixture and previewed
upgrade path under issue #17.
## Delivery slices
1. Add and validate `SimulationConfig`, `InfluxLevel`, typed reports, and
deterministic sub-seeding; no commands or mutation.
2. Add pure influx preview/resolution tests for every outcome and level.
3. Persist idempotent resolution records and expose preview/apply/show/clear.
4. Integrate resolution into diffusion towns, then resident/positioned
characters and protection explanations.
5. Add generic conflict state and pure round resolution.
6. Expose conflict/fight/war preview/apply commands and recovery tests.
7. Run default and portable gates, corruption fixtures, help snapshots, and
release builds; update the live tracker only after each issue's acceptance
gates pass.

View File

@ -36,10 +36,13 @@ worktree creation/edits and conflict-checked one-step undo through the library.
Interactive staging, commits, relationships, and general deletion remain later
workflows.
The next implementation track is the [simulation and world-generation
design](simulation-worldgen-design.md). Its first checkpoint is deterministic,
configuration-driven generation; road topology, event diffusion, and PNG
rendering build on that validated foundation.
The simulation track has deterministic world generation, road topology,
character travel, and spatial event frontiers. The next approved work is the
[shared resolution and conflict design](resolution-conflict-design.md): influx
first, then protected-town/character diffusion outcomes, then fight/war. The
[presentation design](presentation-design.md) is implemented alongside those
slices so every new preview is buffered and exportable rather than adding more
direct terminal printing. PNG map rendering follows those tracker issues.
## Proposed stretch goals

View File

@ -70,6 +70,10 @@ which entities/places have already been affected to avoid accidental repeated
application. Preview output explains why a target is reached and which route
or direct distance was used.
Spatial arrival is implemented. Influx-aware outcomes, protection, character
targeting, and fight/war share the follow-on contract in
[Influx, diffusion resolution, and conflict](resolution-conflict-design.md).
## Map rendering
The repository may reference a base map path plus coordinate bounds, but never

View File

@ -78,9 +78,9 @@ reinforce meaning, but never carry meaning alone.
being moved backward. It never deletes history. Conflicts abort without
changing any layer and list affected fields.
- `efo prune-future` is the recoverable history-removal operation. It always
shows a dry-run, requires `--yes`, rewinds the ID allocator to the first free
ID after HEAD, and leaves a backup containing the epochs, prior allocator,
and removed tags so the complete future can be restored.
shows a dry-run, requires `--yes`, preserves the monotonic ID allocator, and
leaves a backup containing the epochs, allocator, and removed tags so the
complete future can be restored without reusing removed IDs.
- `efo reset --hard <epoch>` is a separate, deliberately destructive escape
hatch modelled after Git. It previews by default and requires `--yes` to
discard transient state, move HEAD, delete newer epochs and their tags, and