docs: prepare tracker simulation and output work
This commit is contained in:
parent
70123bf0d5
commit
4bf484a96e
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue