304 lines
13 KiB
Markdown
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.
|