# Adjudication (“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 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; - `--apply` changes 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 through `stage` and `commit`; - adjudication never deletes a target entity. A master-selected `Destroyed` disposition 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: ```text 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: ```text 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: ```text 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: 1. derive town and character targets according to `character_policy`; 2. show blockers/protection as context for the master's ruling; 3. apply the explicit adjudication to each selected stable target; 4. record `Avoided` targets as resolved, preventing repeated application; 5. stop the event if its resolution is `Destroyed`; 6. 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. ```text 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: ```text 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: ```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. **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. 2. **Complete:** add pure adjudication preview/application tests for every disposition and prove no roll/effect is invented. 3. **Complete:** persist idempotent adjudication records and expose preview/apply/list, with `influx` as a visible alias. 4. **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. 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.