From 17747d7f48959eff6e745178e72ab3e591226fe7 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 22 Sep 2026 03:20:35 +0200 Subject: [PATCH] feat: persist adjudicated event potency --- AGENTS-TASKS.md | 3 + bin_efo/src/commands/adjudicate.rs | 30 +++++++- bin_efo/src/commands/diffuse.rs | 16 ++++- bin_efo/tests/cli_workflows.rs | 48 +++++++++++++ docs/commands.md | 4 ++ docs/issue-audit.md | 2 +- docs/resolution-conflict-design.md | 14 +++- lib_efo/src/adjudication.rs | 106 +++++++++++++++++++++++++++-- lib_efo/src/epoch/epoch_info.rs | 7 +- lib_efo/src/simulation.rs | 12 ++++ lib_efo/src/workspace.rs | 1 + lib_efo/tests/adjudication.rs | 43 +++++++++++- 12 files changed, 273 insertions(+), 13 deletions(-) diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 224a472..fb38926 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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 diff --git a/bin_efo/src/commands/adjudicate.rs b/bin_efo/src/commands/adjudicate.rs index 12a4316..61a0c5b 100644 --- a/bin_efo/src/commands/adjudicate.rs +++ b/bin_efo/src/commands/adjudicate.rs @@ -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::>()?, 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::>(); 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", diff --git a/bin_efo/src/commands/diffuse.rs b/bin_efo/src/commands/diffuse.rs index 1b0e963..ccbbbca 100644 --- a/bin_efo/src/commands/diffuse.rs +++ b/bin_efo/src/commands/diffuse.rs @@ -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 { diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 579e8d3..94b571d 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -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] diff --git a/docs/commands.md b/docs/commands.md index cd08f5d..1838f2a 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -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 diff --git a/docs/issue-audit.md b/docs/issue-audit.md index 8c7f9da..408a28c 100644 --- a/docs/issue-audit.md +++ b/docs/issue-audit.md @@ -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. | diff --git a/docs/resolution-conflict-design.md b/docs/resolution-conflict-design.md index 0299448..8726318 100644 --- a/docs/resolution-conflict-design.md +++ b/docs/resolution-conflict-design.md @@ -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 diff --git a/lib_efo/src/adjudication.rs b/lib_efo/src/adjudication.rs index 7f2b0b2..ec6f00d 100644 --- a/lib_efo/src/adjudication.rs +++ b/lib_efo/src/adjudication.rs @@ -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::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, /// Policy used to interpret dampening and limits. @@ -415,9 +436,25 @@ pub fn preview( spec: &AdjudicationSpec, target: &Entity, tick_or_round: u64, +) -> Result { + 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 { 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, diff --git a/lib_efo/src/epoch/epoch_info.rs b/lib_efo/src/epoch/epoch_info.rs index e51030d..7654f4d 100644 --- a/lib_efo/src/epoch/epoch_info.rs +++ b/lib_efo/src/epoch/epoch_info.rs @@ -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, + /// Current attenuation/exhaustion state keyed by source event UUID. + #[serde(default)] + #[table(skip)] + pub event_adjudications: BTreeMap, } 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(), } } } diff --git a/lib_efo/src/simulation.rs b/lib_efo/src/simulation.rs index 6f21c92..6df7c06 100644 --- a/lib_efo/src/simulation.rs +++ b/lib_efo/src/simulation.rs @@ -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, ) -> Result { 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); } diff --git a/lib_efo/src/workspace.rs b/lib_efo/src/workspace.rs index cab2e13..ba52596 100644 --- a/lib_efo/src/workspace.rs +++ b/lib_efo/src/workspace.rs @@ -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. diff --git a/lib_efo/tests/adjudication.rs b/lib_efo/tests/adjudication.rs index c2dbc55..050c309 100644 --- a/lib_efo/tests/adjudication.rs +++ b/lib_efo/tests/adjudication.rs @@ -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()); +}