feat: add progressive adjudication defaults

This commit is contained in:
Dandaedre 2026-09-22 03:11:26 +02:00
parent 831c07b192
commit dcb3bce2ad
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
9 changed files with 181 additions and 19 deletions

View File

@ -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

View File

@ -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",

View File

@ -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,
&[

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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<ChosenEffect>,
/// 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<ProjectedChange>,
/// Policy used to interpret dampening and limits.
@ -362,14 +418,26 @@ pub fn preview(
) -> Result<AdjudicationReport, AdjudicationError> {
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::<HashSet<_>>();
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(),
));

View File

@ -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);
}