From dcb3bce2ad6f00164040d939b6b8b820649af43f Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 22 Sep 2026 03:11:26 +0200 Subject: [PATCH] feat: add progressive adjudication defaults --- AGENTS-TASKS.md | 3 + bin_efo/src/commands/adjudicate.rs | 10 ++- bin_efo/tests/cli_workflows.rs | 18 +++++ docs/commands.md | 12 ++++ docs/resolution-conflict-design.md | 12 +++- lib_efo/assets/simulation/README.md | 7 +- lib_efo/assets/simulation/default.json | 15 +++- lib_efo/src/adjudication.rs | 94 +++++++++++++++++++++++--- lib_efo/tests/adjudication.rs | 29 ++++++++ 9 files changed, 181 insertions(+), 19 deletions(-) diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 39dc751..224a472 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -238,6 +238,9 @@ and [`docs/presentation-design.md`](docs/presentation-design.md). - [x] Add preview/apply/list `adjudicate` commands plus the familiar `influx` alias and complete help examples. Records deliberately cannot be cleared independently of their effects; use worktree restore or historical revert. +- [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. - [ ] 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 f484550..12a4316 100644 --- a/bin_efo/src/commands/adjudicate.rs +++ b/bin_efo/src/commands/adjudicate.rs @@ -41,10 +41,10 @@ pub struct AdjudicateArgs { #[arg(long, value_enum)] level: AdjudicationLevel, /// External result retained verbatim (Epoch Forge never rolls it). - #[arg(long)] + #[arg(long, default_value = "not recorded")] result: String, /// How the game master says the source affects this target. - #[arg(long, value_enum)] + #[arg(long, value_enum, default_value = "applied")] disposition: AdjudicationDisposition, /// Explicit STAT:DELTA chosen by the game master; repeat for multiple stats. #[arg(long, value_name = "STAT:DELTA")] @@ -116,7 +116,11 @@ fn resolve(args: &AdjudicateArgs, apply: bool) -> Result<(), AppError> { if report.changes.is_empty() { output.push_str("├─ Effects: none\n"); } else { - output.push_str("├─ Effects\n"); + if report.effects_were_defaulted { + output.push_str("├─ Effects (policy defaults)\n"); + } else { + output.push_str("├─ Effects (game-master supplied)\n"); + } for change in &report.changes { output.push_str(&format!( "│ • {:?}: {} → {} ({:+})\n", diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 5e17b6b..579e8d3 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -147,6 +147,24 @@ fn external_adjudications_preview_apply_audit_and_restore() { assert!(preview_text.contains("Nothing changed")); assert_eq!(snapshot(&repo, 0), before); + let default_preview = efo( + &repo, + &[ + "adjudicate", + "preview", + "Ashfall", + "--target", + "town:Haven", + "--level", + "bad", + ], + ); + assert_success(&default_preview); + let default_text = stdout(&default_preview); + assert!(default_text.contains("External result: not recorded")); + assert!(default_text.contains("Effects (policy defaults)")); + assert!(default_text.contains("Health: 40 → 25 (-15)")); + let apply = efo( &repo, &[ diff --git a/docs/commands.md b/docs/commands.md index e4dae08..cd08f5d 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -143,6 +143,18 @@ efo adjudicate apply Plague --target town:Haven --level bad \ efo adjudicate list Plague ``` +For the common case, omit result, disposition, and effects: + +```text +efo adjudicate apply Plague --target town:Haven --level bad +``` + +This uses the configured default effects. The embedded policy progressively +dampens its `health:-20` baseline: excellent 0%, good 25%, mid 50%, bad 75%, +worsen 90%, and apocalypse 100%. An external `--config` can replace both the +baseline and scale. Supplying one or more `--effect` options replaces the +defaults completely. + `influx` is a visible alias for `adjudicate`. `applied` uses the supplied effects in full, `dampened` applies the configured attenuation, and `avoided` or `destroyed` records zero stat change. Applied rulings are audit records in diff --git a/docs/resolution-conflict-design.md b/docs/resolution-conflict-design.md index 34880a1..0299448 100644 --- a/docs/resolution-conflict-design.md +++ b/docs/resolution-conflict-design.md @@ -138,10 +138,18 @@ 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. `--effect` is repeatable and always -explicit. +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 diff --git a/lib_efo/assets/simulation/README.md b/lib_efo/assets/simulation/README.md index c3d4f46..583ab98 100644 --- a/lib_efo/assets/simulation/README.md +++ b/lib_efo/assets/simulation/README.md @@ -6,10 +6,13 @@ commands with `--config PATH`; unknown fields and invalid ranges are rejected. The schema version is independent from the repository and application versions. This policy does not define or perform a roll: the player rolls -outside Epoch Forge and the game master supplies its interpretation and exact -effects. The configuration defines: +outside Epoch Forge and the game master supplies its interpretation. Exact +effects may be supplied for unusual rulings; otherwise the policy supplies a +small baseline effect with progressive level dampening. The configuration defines: - dampened attenuation in basis points (`10000` means the full chosen effect); +- default effects and ordered level multipliers (`0` means fully dampened and + `10000` means the full default effect); - defensive limits for explicit effects, durable records, and text. Keep `policy_id` stable while semantics remain identical. Change it whenever an diff --git a/lib_efo/assets/simulation/default.json b/lib_efo/assets/simulation/default.json index 974c069..f3f988c 100644 --- a/lib_efo/assets/simulation/default.json +++ b/lib_efo/assets/simulation/default.json @@ -1,7 +1,18 @@ { - "schema_version": { "major": 1, "minor": 0 }, - "policy_id": "epoch-forge/adjudication-default-1", + "schema_version": { "major": 1, "minor": 1 }, + "policy_id": "epoch-forge/adjudication-default-2", "dampened_basis_points": 5000, + "default_effects": [ + { "stat": "health", "delta": -20 } + ], + "level_basis_points": { + "excellent": 0, + "good": 2500, + "mid": 5000, + "bad": 7500, + "worsen": 9000, + "apocalypse": 10000 + }, "max_effects": 64, "max_records": 100000, "max_text_bytes": 16384 diff --git a/lib_efo/src/adjudication.rs b/lib_efo/src/adjudication.rs index e9aa69e..7f2b0b2 100644 --- a/lib_efo/src/adjudication.rs +++ b/lib_efo/src/adjudication.rs @@ -17,7 +17,7 @@ use crate::{ }; /// Configuration schema understood by this build. -pub const CURRENT_ADJUDICATION_CONFIG_VERSION: FormatVersion = FormatVersion { major: 1, minor: 0 }; +pub const CURRENT_ADJUDICATION_CONFIG_VERSION: FormatVersion = FormatVersion { major: 1, minor: 1 }; /// Offline-safe canonical safety policy. pub const DEFAULT_ADJUDICATION_CONFIG_JSON: &str = include_str!("../assets/simulation/default.json"); @@ -168,6 +168,10 @@ pub struct AdjudicationConfig { pub policy_id: String, /// Effect multiplier for a dampened disposition, in basis points. pub dampened_basis_points: isize, + /// Default effects used only when the game master supplies none. + pub default_effects: Vec, + /// Progressive multiplier selected by adjudication level. + pub level_basis_points: LevelBasisPoints, /// Maximum effects supplied for one target. pub max_effects: usize, /// Maximum persisted records in one world. @@ -176,6 +180,38 @@ pub struct AdjudicationConfig { pub max_text_bytes: usize, } +/// Multipliers for policy defaults, expressed in basis points. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct LevelBasisPoints { + /// Excellent-result multiplier. + pub excellent: isize, + /// Good-result multiplier. + pub good: isize, + /// Mid-result multiplier. + pub mid: isize, + /// Bad-result multiplier. + pub bad: isize, + /// Worsen-result multiplier. + pub worsen: isize, + /// Apocalypse-result multiplier. + pub apocalypse: isize, +} + +impl LevelBasisPoints { + /// Select the multiplier for one adjudication level. + fn for_level(&self, level: AdjudicationLevel) -> isize { + match level { + AdjudicationLevel::Excellent => self.excellent, + AdjudicationLevel::Good => self.good, + AdjudicationLevel::Mid => self.mid, + AdjudicationLevel::Bad => self.bad, + AdjudicationLevel::Worsen => self.worsen, + AdjudicationLevel::Apocalypse => self.apocalypse, + } + } +} + /// Configuration, validation, or stale-application failure. #[derive(Debug, thiserror::Error)] pub enum AdjudicationError { @@ -272,6 +308,22 @@ impl AdjudicationConfig { "dampened_basis_points must be within 0..=10000".into(), )); } + let levels = [ + self.level_basis_points.excellent, + self.level_basis_points.good, + self.level_basis_points.mid, + self.level_basis_points.bad, + self.level_basis_points.worsen, + self.level_basis_points.apocalypse, + ]; + if levels.iter().any(|value| !(0..=10_000).contains(value)) + || levels.windows(2).any(|pair| pair[0] > pair[1]) + { + return Err(AdjudicationError::Invalid( + "level_basis_points must progress from excellent to apocalypse within 0..=10000" + .into(), + )); + } if self.max_effects == 0 || self.max_effects > 1_000 || self.max_records == 0 @@ -283,6 +335,7 @@ impl AdjudicationConfig { "configured limits are zero or exceed hard safety limits".into(), )); } + validate_effects(&self.default_effects, self.max_effects)?; Ok(()) } } @@ -347,6 +400,9 @@ pub struct AdjudicationReport { pub external_result: String, /// Master explanation retained verbatim. pub note: String, + /// Whether the configured fallback supplied the effects. + #[serde(default)] + pub effects_were_defaulted: bool, /// Stale-checkable projected changes. pub changes: Vec, /// Policy used to interpret dampening and limits. @@ -362,14 +418,26 @@ pub fn preview( ) -> Result { config.validate()?; validate_spec(config, spec)?; - let attenuation = match spec.disposition { + let disposition_attenuation = match spec.disposition { AdjudicationDisposition::Applied => 10_000, AdjudicationDisposition::Dampened => config.dampened_basis_points, AdjudicationDisposition::Avoided | AdjudicationDisposition::Destroyed => 0, }; + let effects_were_defaulted = spec.effects.is_empty(); + let effects = if effects_were_defaulted { + &config.default_effects + } else { + &spec.effects + }; + let level_attenuation = if effects_were_defaulted { + config.level_basis_points.for_level(spec.level) + } else { + 10_000 + }; + let attenuation = scale(disposition_attenuation, level_attenuation); let mut projected = target.clone(); let mut changes = Vec::new(); - for effect in &spec.effects { + for effect in effects { let stat = effect.stat.list_stat(); let before = **projected.get_stats().get_field(&stat); let applied_delta = scale(effect.delta, attenuation); @@ -389,9 +457,10 @@ pub fn preview( after, }); } - let encoded = serde_json::to_vec(&(spec, target.id, tick_or_round)).map_err(|error| { - AdjudicationError::Invalid(format!("cannot identify adjudication: {error}")) - })?; + let encoded = serde_json::to_vec(&(spec, target.id, tick_or_round, effects, attenuation)) + .map_err(|error| { + AdjudicationError::Invalid(format!("cannot identify adjudication: {error}")) + })?; Ok(AdjudicationReport { id: content_id(&encoded), source: spec.source, @@ -401,6 +470,7 @@ pub fn preview( disposition: spec.disposition, external_result: spec.external_result.clone(), note: spec.note.clone(), + effects_were_defaulted, changes, policy_id: config.policy_id.clone(), }) @@ -509,17 +579,21 @@ fn validate_spec( "external result or note exceeds max_text_bytes".into(), )); } - if spec.effects.len() > config.max_effects { + validate_effects(&spec.effects, config.max_effects) +} + +/// Validate effect allocation and reject ambiguous duplicate statistics. +fn validate_effects(effects: &[ChosenEffect], max_effects: usize) -> Result<(), AdjudicationError> { + if effects.len() > max_effects { return Err(AdjudicationError::Invalid( "too many explicit effects".into(), )); } - let unique = spec - .effects + let unique = effects .iter() .map(|effect| effect.stat) .collect::>(); - if unique.len() != spec.effects.len() { + if unique.len() != effects.len() { return Err(AdjudicationError::Invalid( "an adjudication may change each statistic at most once".into(), )); diff --git a/lib_efo/tests/adjudication.rs b/lib_efo/tests/adjudication.rs index 38ef417..c2dbc55 100644 --- a/lib_efo/tests/adjudication.rs +++ b/lib_efo/tests/adjudication.rs @@ -113,3 +113,32 @@ fn explicit_effects_are_clamped_and_invalid_master_input_is_rejected() { wrong_policy.policy_id = "other".into(); assert!(preview(&config, &wrong_policy, &target, 0).is_err()); } + +#[test] +fn omitted_effects_use_progressively_dampened_policy_defaults() { + let config = AdjudicationConfig::embedded().expect("config"); + let target = entity(2, 100); + let expected = [ + (AdjudicationLevel::Excellent, 0), + (AdjudicationLevel::Good, -5), + (AdjudicationLevel::Mid, -10), + (AdjudicationLevel::Bad, -15), + (AdjudicationLevel::Worsen, -18), + (AdjudicationLevel::Apocalypse, -20), + ]; + for (level, delta) in expected { + let mut ruling = spec(&config, AdjudicationDisposition::Applied); + ruling.level = level; + ruling.effects.clear(); + let report = preview(&config, &ruling, &target, 0).expect("default preview"); + assert!(report.effects_were_defaulted); + assert_eq!(report.changes[0].applied_delta, delta); + assert_eq!(report.changes[0].after, 100 + delta); + } + + let mut explicit = spec(&config, AdjudicationDisposition::Applied); + explicit.level = AdjudicationLevel::Excellent; + let report = preview(&config, &explicit, &target, 0).expect("explicit preview"); + assert!(!report.effects_were_defaulted); + assert_eq!(report.changes[0].applied_delta, -40); +}