feat: persist adjudicated event potency
Rust CI Epoch Forge passed all CI checks.
Gitea/epoch_forge/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-09-22 03:20:35 +02:00
parent dcb3bce2ad
commit 17747d7f48
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
12 changed files with 273 additions and 13 deletions

View File

@ -241,6 +241,9 @@ and [`docs/presentation-design.md`](docs/presentation-design.md).
- [x] Make explicit effects optional: embedded/configurable defaults use a
monotonic excellent-to-apocalypse dampening scale, while any `--effect`
replaces the fallback and the audit record identifies which path was used.
- [x] Persist source-event potency outside ordinary statistics, monotonically
dampen future policy-default effects, expose it in command output, and make a
destroyed ruling expire/prevent diffusion with restore/revert recovery.
- [ ] Resolve diffusion arrivals against protected towns and configured
blockers, explaining avoided/dampened/destroyed outcomes.
- [ ] Resolve resident and positioned characters deterministically; document

View File

@ -6,7 +6,7 @@ use clap::{Args, Subcommand};
use lib_efo::{
adjudication::{
AdjudicationConfig, AdjudicationDisposition, AdjudicationLevel, AdjudicationSpec,
ChosenEffect, StatName, apply_to_world, preview,
ChosenEffect, StatName, apply_to_world, preview_at_potency,
},
entity::EntityIdentifier,
stats::EntityType,
@ -103,7 +103,13 @@ fn resolve(args: &AdjudicateArgs, apply: bool) -> Result<(), AppError> {
.collect::<Result<_, _>>()?,
policy_id: config.policy_id.clone(),
};
let report = preview(&config, &spec, target, 0)?;
let source_potency = workspace
.worktree
.world
.event_adjudications
.get(&source)
.map_or(10_000, |state| state.potency_basis_points);
let report = preview_at_potency(&config, &spec, target, 0, source_potency)?;
let mut output = format!(
"Adjudication preview · {} · {} · {}\n├─ External result: {}\n├─ Target: {} (@{})\n",
level_label(report.level),
@ -129,6 +135,16 @@ fn resolve(args: &AdjudicateArgs, apply: bool) -> Result<(), AppError> {
}
}
output.push_str(&format!("└─ Record: @{}\n", report.id));
output.push_str(&format!(
" Source potency: {}% → {}%{}\n",
report.source_potency_before / 100,
report.source_potency_after / 100,
if report.disposition == AdjudicationDisposition::Destroyed {
" (destroyed)"
} else {
""
}
));
if !apply {
output.push_str("Nothing changed. Use `efo adjudicate apply …` to update the worktree.\n");
print!("{output}");
@ -164,6 +180,16 @@ fn list(args: &AdjudicateListArgs) -> Result<(), AppError> {
.filter(|record| source.is_none_or(|id| record.source == id))
.collect::<Vec<_>>();
let mut output = format!("Adjudications · {} record(s)\n", records.len());
if let Some(source) = source
&& let Some(state) = workspace.worktree.world.event_adjudications.get(&source)
{
output.push_str(&format!(
"Source event · potency {}%{} · last @{}\n",
state.potency_basis_points / 100,
if state.destroyed { " · destroyed" } else { "" },
state.last_record
));
}
for record in records {
output.push_str(&format!(
"• @{} · event @{} → @{} · {} · {} · {}\n",

View File

@ -81,6 +81,13 @@ fn start(args: &DiffuseStartArgs) -> Result<(), AppError> {
"Diffusion preview · {} destination(s)",
state.frontier.len()
);
let potency = workspace
.worktree
.world
.event_adjudications
.get(&event)
.map_or(10_000, |state| state.potency_basis_points);
println!(" Source potency · {}%", potency / 100);
for target in &state.frontier {
let town = workspace
.worktree
@ -114,7 +121,14 @@ fn tick(args: &DiffuseTickArgs) -> Result<(), AppError> {
println!("Diffusion tick preview · {} tick(s)", args.amount);
println!("├─ Newly reached {}", report.reached.len());
for (event, town) in &report.reached {
println!("│ • event @{event} → town @{town}");
let potency = preview
.event_adjudications
.get(event)
.map_or(10_000, |state| state.potency_basis_points);
println!(
"│ • event @{event} → town @{town} · potency {}%",
potency / 100
);
}
println!("└─ Expired {}", report.expired.len());
if !args.apply {

View File

@ -194,11 +194,21 @@ fn external_adjudications_preview_apply_audit_and_restore() {
.len(),
1
);
assert_eq!(
snapshot(&repo, 0)["event_adjudications"]
.as_object()
.expect("event adjudication states")
.values()
.next()
.expect("source state")["potency_basis_points"],
7500
);
let list = efo(&repo, &["adjudicate", "list", "Ashfall"]);
assert_success(&list);
assert!(stdout(&list).contains("d20=4"));
assert!(stdout(&list).contains("dampened"));
assert!(stdout(&list).contains("potency 75%"));
let duplicate = efo(
&repo,
@ -228,6 +238,44 @@ fn external_adjudications_preview_apply_audit_and_restore() {
assert_success(&efo(&repo, &["restore", "--worktree", "--all"]));
assert_eq!(snapshot(&repo, 0), before);
assert_success(&efo(&repo, &["diffuse", "start", "Ashfall", "--apply"]));
let destroyed = efo(
&repo,
&[
"adjudicate",
"apply",
"Ashfall",
"--target",
"town:Haven",
"--level",
"excellent",
"--disposition",
"destroyed",
],
);
assert_success(&destroyed);
assert!(stdout(&destroyed).contains("0% (destroyed)"));
assert!(
snapshot(&repo, 0)["diffusions"]
.as_object()
.expect("diffusions")
.values()
.next()
.expect("active diffusion")["expired"]
.as_bool()
.expect("expired flag")
);
let diffusion = efo(&repo, &["diffuse", "start", "Ashfall"]);
assert!(!diffusion.status.success());
assert!(
stderr(&diffusion).contains("destroyed by adjudication"),
"unexpected diffusion error: {}",
stderr(&diffusion)
);
assert_success(&efo(&repo, &["restore", "--worktree", "--all"]));
assert_eq!(snapshot(&repo, 0), before);
}
#[test]

View File

@ -160,6 +160,10 @@ effects in full, `dampened` applies the configured attenuation, and `avoided`
or `destroyed` records zero stat change. Applied rulings are audit records in
the worktree. Use `efo restore --worktree --all` to undo the ruling and its
effects together; audit records cannot be cleared independently from effects.
Each ruling also marks the source event with remaining potency. Later default
effects are multiplied by that percentage. A destroyed event has 0% potency,
stops an active frontier, and cannot start another diffusion; restore or revert
the ruling to recover it. `efo adjudicate list EVENT` displays this state.
## Generation and output

View File

@ -18,7 +18,7 @@ absent.
| [#12 Add fight/war](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/12) | Not implemented. The implementation-ready design uses generic multi-side conflict records and reuses explicit game-master adjudications. | Deliver after adjudication persistence and diffusion integration; see `resolution-conflict-design.md`. |
| [#11 Epoch Diffing](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/11) | Addressed: epoch and layer comparisons share a deterministic, serializable typed diff with changed-field details and importance classification. | Extend the type rather than parsing terminal output when structured formats arrive. |
| [#10 Display functions](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10) | Partially addressed: unified `show`, entity detail, and diff rendering are buffered. Most commands and several legacy library helpers still print directly; saving/structured output is absent. | Implement the renderer/sink migration and acceptance inventory in `presentation-design.md`. |
| [#9 Adding influx](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9) | Corrected foundation implemented: “influx” is a player-made external roll adjudicated by the master. The library records all six master-assigned levels, explicit effects, applied/dampened/avoided/destroyed dispositions, clamped previews, and stale checks; it never rolls. | Persist idempotent adjudication records, then implement `adjudicate` preview/apply/show/clear with `influx` as an alias. |
| [#9 Adding influx](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/9) | Functionally complete: `adjudicate`/`influx` records the external roll and all six levels/dispositions, supports progressive or explicit effects, persists source potency, and makes destroyed events stop diffusion. Audit, stale-state, restoration, and repository validation are covered. | Close the live tracker issue after review. |
| [#8 Event diffusion](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/8) | Partially addressed: deterministic road/direct town frontiers, affected sets, expiry, previewed ticks, and reversible application exist. Influx-aware outcomes, protected-town avoidance, and character targeting remain. | Integrate the shared resolution engine using the explicit #8 acceptance gates in `resolution-conflict-design.md`. |
| [#6 HashMap/HashSet](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/6) | Addressed without format churn: `EntityIndex` provides ephemeral UUID/name hash indexes and duplicate-ID detection over the stable vector representation. Repository validation uses the index and hash lookup for relationships. | Rebuild indexes after mutation; never persist them. |

View File

@ -171,6 +171,14 @@ Acceptance gates:
- 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 existing `DiffusionState` already stores origin, elapsed ticks, expiry,
@ -289,8 +297,10 @@ upgrade path under issue #17.
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. Integrate resolution into diffusion towns, then resident/positioned
characters and protection explanations.
4. **Partially complete:** source attenuation now affects future default
resolutions and destroyed sources stop diffusion. Next integrate automatic
arrival targets, then resident/positioned characters and protection
explanations.
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

View File

@ -212,6 +212,17 @@ impl LevelBasisPoints {
}
}
/// Durable attenuation/exhaustion state attached to a source event.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EventAdjudicationState {
/// Remaining strength used by later policy-default resolutions.
pub potency_basis_points: isize,
/// Whether the game master explicitly destroyed the event.
pub destroyed: bool,
/// Most recent ruling that changed this state.
pub last_record: Uuid,
}
/// Configuration, validation, or stale-application failure.
#[derive(Debug, thiserror::Error)]
pub enum AdjudicationError {
@ -262,6 +273,10 @@ pub enum AdjudicationError {
}
impl AdjudicationConfig {
/// Return the configured progressive multiplier for a level.
pub fn level_multiplier(&self, level: AdjudicationLevel) -> isize {
self.level_basis_points.for_level(level)
}
/// Load and validate the embedded policy.
pub fn embedded() -> Result<Self, AdjudicationError> {
Self::decode(
@ -403,6 +418,12 @@ pub struct AdjudicationReport {
/// Whether the configured fallback supplied the effects.
#[serde(default)]
pub effects_were_defaulted: bool,
/// Source potency observed while previewing.
#[serde(default = "full_basis_points")]
pub source_potency_before: isize,
/// Source potency retained after this ruling.
#[serde(default = "full_basis_points")]
pub source_potency_after: isize,
/// Stale-checkable projected changes.
pub changes: Vec<ProjectedChange>,
/// Policy used to interpret dampening and limits.
@ -415,9 +436,25 @@ pub fn preview(
spec: &AdjudicationSpec,
target: &Entity,
tick_or_round: u64,
) -> Result<AdjudicationReport, AdjudicationError> {
preview_at_potency(config, spec, target, tick_or_round, 10_000)
}
/// Preview while accounting for durable attenuation already on the source.
pub fn preview_at_potency(
config: &AdjudicationConfig,
spec: &AdjudicationSpec,
target: &Entity,
tick_or_round: u64,
source_potency: isize,
) -> Result<AdjudicationReport, AdjudicationError> {
config.validate()?;
validate_spec(config, spec)?;
if !(0..=10_000).contains(&source_potency) {
return Err(AdjudicationError::Invalid(
"source potency must be within 0..=10000 basis points".into(),
));
}
let disposition_attenuation = match spec.disposition {
AdjudicationDisposition::Applied => 10_000,
AdjudicationDisposition::Dampened => config.dampened_basis_points,
@ -434,7 +471,19 @@ pub fn preview(
} else {
10_000
};
let attenuation = scale(disposition_attenuation, level_attenuation);
let attenuation = scale(
scale(disposition_attenuation, level_attenuation),
if effects_were_defaulted {
source_potency
} else {
10_000
},
);
let source_potency_after = if spec.disposition == AdjudicationDisposition::Destroyed {
0
} else {
source_potency.min(config.level_multiplier(spec.level))
};
let mut projected = target.clone();
let mut changes = Vec::new();
for effect in effects {
@ -457,10 +506,21 @@ pub fn preview(
after,
});
}
let encoded = serde_json::to_vec(&(spec, target.id, tick_or_round, effects, attenuation))
.map_err(|error| {
AdjudicationError::Invalid(format!("cannot identify adjudication: {error}"))
})?;
let encoded = serde_json::to_vec(&(
spec,
target.id,
tick_or_round,
effects,
attenuation,
if effects_were_defaulted {
source_potency
} else {
10_000
},
))
.map_err(|error| {
AdjudicationError::Invalid(format!("cannot identify adjudication: {error}"))
})?;
Ok(AdjudicationReport {
id: content_id(&encoded),
source: spec.source,
@ -471,6 +531,8 @@ pub fn preview(
external_result: spec.external_result.clone(),
note: spec.note.clone(),
effects_were_defaulted,
source_potency_before: source_potency,
source_potency_after,
changes,
policy_id: config.policy_id.clone(),
})
@ -527,11 +589,40 @@ pub fn apply_to_world(
let target = updated.find_entity_strict_as_mut(report.target, Some(target_type))?;
apply_to_target(report, target)?;
updated.adjudications.insert(report.id, report.clone());
updated.event_adjudications.insert(
report.source,
EventAdjudicationState {
potency_basis_points: report.source_potency_after,
destroyed: report.disposition == AdjudicationDisposition::Destroyed,
last_record: report.id,
},
);
if report.disposition == AdjudicationDisposition::Destroyed
&& let Some(diffusion) = updated.diffusions.get_mut(&report.source)
{
diffusion.expired = true;
}
Ok(updated)
}
/// Validate persisted audit-record references and structural invariants.
pub fn validate_adjudications(world: &EpochInfo) -> Result<(), AdjudicationError> {
for (event, state) in &world.event_adjudications {
world.find_entity_strict(*event, Some(EntityType::Event))?;
if !(0..=10_000).contains(&state.potency_basis_points)
|| (state.destroyed && state.potency_basis_points != 0)
{
return Err(AdjudicationError::Invalid(format!(
"event @{event} has invalid adjudication state"
)));
}
if !world.adjudications.contains_key(&state.last_record) {
return Err(AdjudicationError::Invalid(format!(
"event @{event} refers to missing adjudication @{}",
state.last_record
)));
}
}
for (key, report) in &world.adjudications {
if key != &report.id {
return Err(AdjudicationError::Invalid(format!(
@ -562,6 +653,11 @@ pub fn validate_adjudications(world: &EpochInfo) -> Result<(), AdjudicationError
Ok(())
}
/// Serde default for records written before source attenuation existed.
const fn full_basis_points() -> isize {
10_000
}
/// Validate a master-authored interpretation before previewing it.
fn validate_spec(
config: &AdjudicationConfig,

View File

@ -13,7 +13,7 @@ use std::fs::create_dir_all;
use uuid::Uuid;
use crate::{
adjudication::AdjudicationReport,
adjudication::{AdjudicationReport, EventAdjudicationState},
entity::{Entity, EntityIdentifier},
epoch::{
EpochId, SUB_NAME, SUBFOLDER_NAMING, TagList,
@ -101,6 +101,10 @@ pub struct EpochInfo {
#[serde(default)]
#[table(skip)]
pub adjudications: BTreeMap<Uuid, AdjudicationReport>,
/// Current attenuation/exhaustion state keyed by source event UUID.
#[serde(default)]
#[table(skip)]
pub event_adjudications: BTreeMap<Uuid, EventAdjudicationState>,
}
impl Prettiable for EpochInfo {}
@ -124,6 +128,7 @@ impl Default for EpochInfo {
mobility: BTreeMap::new(),
diffusions: BTreeMap::new(),
adjudications: BTreeMap::new(),
event_adjudications: BTreeMap::new(),
}
}
}

View File

@ -108,6 +108,11 @@ pub struct DiffusionTick {
/// Invalid topology or travel request.
#[derive(Debug, thiserror::Error)]
pub enum SimulationError {
/// A destroyed event cannot begin another diffusion.
#[error(
"event @{0} was destroyed by adjudication; restore or revert that ruling before diffusing it"
)]
EventDestroyed(Uuid),
/// A referenced character does not exist.
#[error("character @{0} does not exist")]
CharacterMissing(Uuid),
@ -251,6 +256,13 @@ pub fn plan_diffusion(
expires_after: Option<u64>,
) -> Result<DiffusionState, SimulationError> {
validate_roads(world)?;
if world
.event_adjudications
.get(&event)
.is_some_and(|state| state.destroyed)
{
return Err(SimulationError::EventDestroyed(event));
}
if road_speed == 0 || direct_speed == 0 {
return Err(SimulationError::InvalidSpeed);
}

View File

@ -823,6 +823,7 @@ fn copy_world_metadata(source: &EpochInfo, destination: &mut EpochInfo) {
destination.tags = source.tags.clone();
destination.summary = source.summary.clone();
destination.adjudications = source.adjudications.clone();
destination.event_adjudications = source.event_adjudications.clone();
}
/// Validate stable identity, collection type, and relationship targets.

View File

@ -3,9 +3,10 @@ use std::fs;
use lib_efo::{
adjudication::{
AdjudicationConfig, AdjudicationDisposition, AdjudicationLevel, AdjudicationSpec,
ChosenEffect, StatName, apply_to_target, preview,
ChosenEffect, StatName, apply_to_target, apply_to_world, preview, preview_at_potency,
},
entity::Entity,
epoch::EpochInfo,
stats::{EntityType, ListStats, Modification, StatPair},
};
use uuid::Uuid;
@ -142,3 +143,43 @@ fn omitted_effects_use_progressively_dampened_policy_defaults() {
assert!(!report.effects_were_defaulted);
assert_eq!(report.changes[0].applied_delta, -40);
}
#[test]
fn source_attenuation_persists_and_destroyed_events_stop_diffusion() {
let config = AdjudicationConfig::embedded().expect("config");
let mut event = Entity::default();
event.id = Uuid::from_u128(1);
event.entity_type = EntityType::Event;
let target = entity(2, 100);
let mut world = EpochInfo::default();
world.events.push(event);
world.towns.push(target.clone());
let mut ruling = spec(&config, AdjudicationDisposition::Applied);
ruling.effects.clear();
let first = preview(&config, &ruling, &target, 0).expect("first preview");
assert_eq!(first.source_potency_after, 7500);
let world = apply_to_world(&world, &config, &first, EntityType::Town).expect("first apply");
assert_eq!(
world.event_adjudications[&ruling.source].potency_basis_points,
7500
);
let changed_target = &world.towns[0];
let second =
preview_at_potency(&config, &ruling, changed_target, 1, 7500).expect("attenuated preview");
assert_eq!(second.changes[0].applied_delta, -11);
ruling.disposition = AdjudicationDisposition::Destroyed;
ruling.external_result = "the source is destroyed".into();
let destroyed =
preview_at_potency(&config, &ruling, changed_target, 2, 7500).expect("destroyed preview");
let world =
apply_to_world(&world, &config, &destroyed, EntityType::Town).expect("destroyed apply");
assert!(world.event_adjudications[&ruling.source].destroyed);
assert_eq!(
world.event_adjudications[&ruling.source].potency_basis_points,
0
);
assert!(lib_efo::simulation::plan_diffusion(&world, ruling.source, 100, 25, None).is_err());
}