diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index b99e95f..7a2afff 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 4e69748..1adfd99 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/issue-audit.md b/docs/issue-audit.md index 30066e0..265c5fb 100644 --- a/docs/issue-audit.md +++ b/docs/issue-audit.md @@ -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. diff --git a/docs/presentation-design.md b/docs/presentation-design.md new file mode 100644 index 0000000..fc3ab2e --- /dev/null +++ b/docs/presentation-design.md @@ -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, + force: bool, + color: Auto | Always | Never +} + +Document { + title: Option, + blocks: Vec +} + +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. + diff --git a/docs/repository.md b/docs/repository.md index 5806e60..8256837 100644 --- a/docs/repository.md +++ b/docs/repository.md @@ -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, diff --git a/docs/resolution-conflict-design.md b/docs/resolution-conflict-design.md new file mode 100644 index 0000000..bd11a1b --- /dev/null +++ b/docs/resolution-conflict-design.md @@ -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 +stopped: Option +character_policy: Residents | Positioned | Both | None +influx: Option +``` + +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 +conflicts: BTreeMap +``` + +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. + diff --git a/docs/roadmap.md b/docs/roadmap.md index b838264..19b59c4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 diff --git a/docs/simulation-worldgen-design.md b/docs/simulation-worldgen-design.md index ed1ca59..9d0d85a 100644 --- a/docs/simulation-worldgen-design.md +++ b/docs/simulation-worldgen-design.md @@ -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 diff --git a/docs/staging-design.md b/docs/staging-design.md index aa6da71..a3f84ac 100644 --- a/docs/staging-design.md +++ b/docs/staging-design.md @@ -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 ` 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