epoch_forge/docs/resolution-conflict-design.md

304 lines
13 KiB
Markdown

# 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.
The implementation uses the versioned `epoch-forge/conflict-gm-1` ruleset.
```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, 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:
```text
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:
```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. **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. **Complete:** add generic conflict state and pure round resolution.
6. **Complete:** 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.