12 KiB
Adjudication (“influx”), diffusion resolution, and conflict design
This is the implementation contract for tracker issues #9, #8, and #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
An adjudication (formerly called an “influx”) is a player-made roll outside Epoch Forge. The game master interprets that result, chooses its level, disposition, targets, and exact effects, then uses Epoch Forge to preview and record the ruling. Epoch Forge must never invent, reroll, or reinterpret it.
Adjudication is inspectable and subordinate to the Git-like workflow:
- preview is the default and never writes;
--applychanges only the complete worktree snapshot under the repository writer lock;- staging and committing remain explicit separate operations;
- previews state the external result, master note, selected targets, disposition, policy, and exact projected changes;
- replaying the same explicit ruling against the same state 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 throughstageandcommit; - adjudication never deletes a target entity. A master-selected
Destroyeddisposition marks the source event/conflict exhausted; entity deletion is a separate explicit operation.
The model remains setting-agnostic. “War”, “plague”, “merger”, “strike”, and “market shock” are labels over the same participant, explicit ruling, and effect primitives. Fantasy-specific unit classes or damage types do not belong in the core.
Shared adjudication recorder
Influx levels
AdjudicationLevel is a stable serialized enum and a Clap value enum. It is
assigned by the master; it does not imply a numeric roll or automatic effect:
| Level | Intent |
|---|---|
excellent |
exceptional beneficial ruling |
good |
beneficial ruling |
mid |
weak, neutral, or mixed ruling |
bad |
harmful ruling |
worsen |
strongly harmful/escalating ruling |
apocalypse |
extreme harmful ruling |
The names are compatibility vocabulary from the issue, not hard-coded story
meaning. Parsed aliases 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:
AdjudicationSpec {
level, disposition, source_event,
external_result, note, chosen_effects, policy_id
}
AdjudicationRecord {
id, source, target, tick_or_round,
level, disposition, external_result, note,
before_and_after_changes, policy_id
}
Disposition = Applied | Dampened | Avoided | Destroyed
Records use stable content-derived UUIDs and are ordered by
(tick_or_round, source, target, id). Identical adjudications therefore cannot
be accidentally applied twice. No RNG exists in this subsystem.
Chosen effects are typed field/stat deltas, not formatted text. Every previewed change carries before/applied-delta/projected-after values and the normal clamping policy. Application verifies the target still has the recorded before value; stale state aborts the whole transaction with recovery guidance.
Disposition and attenuation
The game master explicitly chooses the disposition:
Applied: apply every chosen effect in full;Dampened: apply chosen effects using the configured attenuation;Avoided: record the target's avoidance and apply no effects;Destroyed: stop/exhaust the source and apply no target effects.
Epoch Forge applies no hidden inference. Protection and blockers are context shown to the master, not an automatic roll. Invalid stat names, duplicate effects, excessive effect counts, stale targets, and unknown policies fail before mutation.
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. It does not
edit the source's base stats.
Configuration
lib_efo/assets/simulation/default.json contains a versioned
AdjudicationConfig independent of repository and worldgen versions. It owns
only policy and safety—not game-master decisions:
- dampened attenuation;
- maximum effects, records, and text sizes;
- a stable policy identifier.
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: adjudication surface
Proposed CLI:
efo adjudicate preview EVENT --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-20
efo adjudicate apply EVENT ...
efo adjudicate show EVENT
efo adjudicate clear EVENT [--yes]
efo influx ... # visible legacy/domain alias
preview and apply are intentionally separate words; apply still prints
the complete preview before its success line. --result is descriptive text,
not a value the program interprets. --effect is repeatable and always
explicit.
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, and appear in help;
- the same explicit ruling/policy/state yields byte-equivalent typed reports;
- applied, dampened, avoided, and destroyed dispositions 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;
- tests prove that the program never generates a roll or an unrequested effect.
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:
resolved: BTreeMap<TargetRef, AdjudicationId>
stopped: Option<StopReason>
character_policy: Residents | Positioned | Both | None
adjudication: Option<AdjudicationSpec>
When a tick reaches a town:
- derive town and character targets according to
character_policy; - show blockers/protection as context for the master's ruling;
- apply the explicit adjudication to each selected stable target;
- record
Avoidedtargets as resolved, preventing repeated application; - stop the event if its resolution is
Destroyed; - include route, protection source, external result, master note, and projected effects in the tick report.
Protection is explicit and generic. Positioned Blocker entities and typed
links are shown to the master as context. A protected town is not silently
omitted: the report says which blocker/link is relevant and records whether
the master ruled that 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 adjudication records instead of directly coupling entities.
ConflictState {
id, name, kind, sides, 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:
efo conflict start NAME --kind fight --side red:town:Haven --side blue:org:Guild
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 reapply an already recorded round.
Acceptance gates cover two and three-sided conflicts, mixed entity types, fight completion, multi-round war, victory/stalemate, participant removal, identical-ruling 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:
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
- Corrected and complete: add and validate
AdjudicationConfig, all six master-assigned levels, explicit dispositions/effects, stale-checkable typed reports, and reproducible release packaging; no commands or mutation. - Complete: add pure adjudication preview/application tests for every disposition and prove no roll/effect is invented.
- Persist idempotent adjudication records and expose preview/apply/show/clear.
- Integrate resolution into diffusion towns, then resident/positioned characters and protection explanations.
- Add generic conflict state and pure round resolution.
- Expose conflict/fight/war preview/apply commands and recovery tests.
- Run default and portable gates, corruption fixtures, help snapshots, and release builds; update the live tracker only after each issue's acceptance gates pass.