13 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 list [EVENT]
efo influx ... # visible legacy/domain alias
The concise common case needs only the source, target, and level:
efo adjudicate apply Plague --target town:Haven --level bad
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. Both it and --disposition applied have
safe defaults. --effect is repeatable; when omitted, the policy's base
effects are scaled progressively from excellent (most dampened) through
apocalypse (full effect). Any explicit effect list replaces that fallback.
Audit records are not independently clearable: removing a record while leaving its effects would make the world misleading. Restore the worktree before a commit, or use the normal historical revert workflow after a commit.
The implemented single-target form supports stable IDs and unambiguous name
prefixes for every stored entity kind. Semantic groups (towns, characters,
organisations, reached) remain part of the diffusion-integration slice;
reached will consume 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.
Implemented source behavior: every applied adjudication stores the event's
remaining potency separately from ordinary entity statistics. The configured
level multiplier can only maintain or reduce that potency. Later policy-default
effects include the remaining potency in their attenuation, while explicit GM
effects remain exact overrides. A destroyed ruling sets potency to zero,
expires an existing frontier, and prevents a new diffusion from starting.
adjudicate list EVENT and diffusion output expose the current percentage.
Issue #8: finish diffusion resolution
The implemented DiffusionState stores origin, elapsed ticks, expiry, ordered
town frontier, affected towns, pending arrivals, and target-to-adjudication
resolution records. The character policy is selected per resolution. Destroyed
source state and diffusion expiry together provide the stop reason; the full
adjudication remains in its durable audit record instead of being duplicated.
When a tick reaches a town, diffuse resolve now:
- 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. The implemented policy conservatively excludes in-transit characters until interpolated travel positions exist; help and reports 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.
The implementation uses the versioned epoch-forge/conflict-gm-1 ruleset.
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, single-resolution conflict. A war is persistent and advances in explicit rounds. Neither automatically creates/deletes normal entities. Resolution applies explicit or configured-default stat effects; rulesets that generate ordinary Event entities remain a future extension.
Implemented CLI:
efo conflict start NAME --kind fight --side red:town:Haven --side blue:org:Guild
efo conflict advance CONFLICT --side-outcome red:good:applied \
--side-outcome blue:bad:dampened [--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. In the initial ruleset, a fight with multiple sides remaining stalemates after round one; a war remains active until one side remains; zero sides is a stalemate. A command cannot advance a finished 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.
- Complete: persist idempotent adjudication records and expose
preview/apply/list, with
influxas a visible alias. - Complete: ticks create pending arrivals; source attenuation affects future defaults; resolution atomically covers towns and selected resident/positioned characters, explains positioned/linked protection, records avoided targets, and stops diffusion when destroyed.
- Complete: add generic conflict state and pure round resolution.
- Complete: 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.