feat: record external adjudications

This commit is contained in:
Dandaedre 2026-09-22 02:59:15 +02:00
parent 9481146bce
commit 831c07b192
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
12 changed files with 505 additions and 15 deletions

View File

@ -233,10 +233,11 @@ and [`docs/presentation-design.md`](docs/presentation-design.md).
and explicit effects; Epoch Forge never rolls or invents an effect.
- [x] Implement all six stable master-assigned levels, explicit effects,
disposition-controlled attenuation, clamping, and stale-checkable reports.
- [ ] Persist idempotent, stale-state-checked adjudication records with workspace
- [x] Persist idempotent, stale-state-checked adjudication records with workspace
and historical `fsck` validation.
- [ ] Add preview/apply/show/clear `adjudicate` commands plus the familiar
`influx` alias and complete help examples.
- [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.
- [ ] Resolve diffusion arrivals against protected towns and configured
blockers, explaining avoided/dampened/destroyed outcomes.
- [ ] Resolve resident and positioned characters deterministically; document
@ -245,9 +246,11 @@ and [`docs/presentation-design.md`](docs/presentation-design.md).
fight/war round resolution, victory, stalemate, and explicit ending.
- [ ] Add conflict commands and focused fight/war aliases with preview-first,
worktree-only application and restore/stage/commit/revert coverage.
- [ ] Cover every adjudication level/disposition, repeated application, stale
state, corruption, allocation limits,
- [ ] Cover every adjudication level/disposition, corruption, allocation limits,
multi-side conflict, and diffusion/conflict integration.
- [x] Cover deterministic preview, explicit effects, attenuation, avoided and
destroyed no-op effects, clamping, stale/repeated application, CLI audit,
aliasing, and worktree restoration.
### Presentation completion (#10)

View File

@ -74,7 +74,7 @@ Run `efo --help`, `efo <command> --help`, or see the
| Repository | Initialise format 1.0; inspect; lock and recover transactional writes | Future 1.x migration tooling; discovery from child directories; integrity repair |
| Timeline | Commit, advance, switch, log, tag, summarise, diff, reviewable/committed revert, backed-up pruning, and explicit hard reset | Branching and merging |
| Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations |
| Generation and simulation | Generate deterministic seeded worlds; define roads; preview/apply travel and spatial event diffusion | Influx, conflict simulation, and setting template packs |
| Generation and simulation | Generate deterministic seeded worlds; define roads; preview/apply travel and spatial event diffusion; record player rolls and explicit game-master adjudications (`influx`) | Automatic arrival targeting, conflict simulation, and setting template packs |
| Interfaces | Complete CLI; `efo-tui` browser and entity editor | TUI staging/commits; GUI/web (out of scope) |
`efo show all` gives a world overview; per-type commands such as

View File

@ -8,6 +8,7 @@
#![warn(missing_docs, clippy::missing_docs_in_private_items)]
pub mod adjudicate;
pub mod diffuse;
pub mod entity_generic;
pub mod epoch;

View File

@ -0,0 +1,260 @@
//! Record and apply player-rolled, game-master-authored resolutions.
use std::{path::Path, str::FromStr};
use clap::{Args, Subcommand};
use lib_efo::{
adjudication::{
AdjudicationConfig, AdjudicationDisposition, AdjudicationLevel, AdjudicationSpec,
ChosenEffect, StatName, apply_to_world, preview,
},
entity::EntityIdentifier,
stats::EntityType,
workspace::Workspace,
};
use crate::error::AppError;
/// Adjudication operations (also available as `influx`).
#[derive(Debug, Subcommand)]
pub enum AdjudicateCmd {
/// Preview a ruling without changing the worktree.
Preview(AdjudicateArgs),
/// Apply a ruling and record it in the worktree.
Apply(AdjudicateArgs),
/// List recorded rulings, optionally restricted to one event.
List(AdjudicateListArgs),
}
/// One external roll and the game master's explicit ruling.
#[derive(Debug, Args)]
#[command(
after_long_help = "EXAMPLES:\n efo adjudicate preview Plague --target town:Haven --level bad --result 'd20=4' --disposition dampened --effect health:-8\n efo influx apply Plague --target character:Aria --level good --result '2d6=11' --disposition applied --effect happiness:3"
)]
pub struct AdjudicateArgs {
/// Source event name/prefix or @UUID.
source: EntityIdentifier,
/// Target as KIND:IDENTIFIER (character, town, org, calamity, blocker, or event).
#[arg(long, value_name = "KIND:IDENTIFIER")]
target: String,
/// Game-master interpretation of the external result.
#[arg(long, value_enum)]
level: AdjudicationLevel,
/// External result retained verbatim (Epoch Forge never rolls it).
#[arg(long)]
result: String,
/// How the game master says the source affects this target.
#[arg(long, value_enum)]
disposition: AdjudicationDisposition,
/// Explicit STAT:DELTA chosen by the game master; repeat for multiple stats.
#[arg(long, value_name = "STAT:DELTA")]
effect: Vec<String>,
/// Optional explanation retained in the audit record.
#[arg(long, default_value = "")]
note: String,
/// Complete replacement policy JSON.
#[arg(long)]
config: Option<std::path::PathBuf>,
}
/// Filters for recorded adjudications.
#[derive(Debug, Args)]
pub struct AdjudicateListArgs {
/// Event name/prefix or @UUID. Omit to show all records.
source: Option<EntityIdentifier>,
}
/// Dispatch an adjudication operation.
pub fn handle(command: &AdjudicateCmd) -> Result<(), AppError> {
match command {
AdjudicateCmd::Preview(args) => resolve(args, false),
AdjudicateCmd::Apply(args) => resolve(args, true),
AdjudicateCmd::List(args) => list(args),
}
}
/// Preview and optionally persist one ruling.
fn resolve(args: &AdjudicateArgs, apply: bool) -> Result<(), AppError> {
let mut workspace = Workspace::open(Path::new("."))?;
let config = match &args.config {
Some(path) => AdjudicationConfig::load(path)?,
None => AdjudicationConfig::embedded()?,
};
let source = workspace
.worktree
.world
.find_entity_of_type(&Some(args.source.clone()), &EntityType::Event)?
.id;
let (target_type, target_identifier) = parse_target(&args.target)?;
let target = workspace
.worktree
.world
.find_entity_of_type(&Some(target_identifier), &target_type)?;
let spec = AdjudicationSpec {
level: args.level,
disposition: args.disposition,
source,
external_result: args.result.clone(),
note: args.note.clone(),
effects: args
.effect
.iter()
.map(|raw| parse_effect(raw))
.collect::<Result<_, _>>()?,
policy_id: config.policy_id.clone(),
};
let report = preview(&config, &spec, target, 0)?;
let mut output = format!(
"Adjudication preview · {} · {} · {}\n├─ External result: {}\n├─ Target: {} (@{})\n",
level_label(report.level),
disposition_label(report.disposition),
target_type_label(target_type),
report.external_result,
target.name,
target.id
);
if report.changes.is_empty() {
output.push_str("├─ Effects: none\n");
} else {
output.push_str("├─ Effects\n");
for change in &report.changes {
output.push_str(&format!(
"│ • {:?}: {} → {} ({:+})\n",
change.stat, change.before, change.after, change.applied_delta
));
}
}
output.push_str(&format!("└─ Record: @{}\n", report.id));
if !apply {
output.push_str("Nothing changed. Use `efo adjudicate apply …` to update the worktree.\n");
print!("{output}");
return Ok(());
}
workspace.worktree.world =
apply_to_world(&workspace.worktree.world, &config, &report, target_type)?;
workspace.save_worktree("apply adjudication")?;
output.push_str("✓ Ruling recorded in the worktree. Undo: efo restore --worktree --all\n");
print!("{output}");
Ok(())
}
/// List audit records in stable key order.
fn list(args: &AdjudicateListArgs) -> Result<(), AppError> {
let workspace = Workspace::open(Path::new("."))?;
let source = args
.source
.as_ref()
.map(|identifier| {
workspace
.worktree
.world
.find_entity_of_type(&Some(identifier.clone()), &EntityType::Event)
.map(|entity| entity.id)
})
.transpose()?;
let records = workspace
.worktree
.world
.adjudications
.values()
.filter(|record| source.is_none_or(|id| record.source == id))
.collect::<Vec<_>>();
let mut output = format!("Adjudications · {} record(s)\n", records.len());
for record in records {
output.push_str(&format!(
"• @{} · event @{} → @{} · {} · {} · {}\n",
record.id,
record.source,
record.target,
level_label(record.level),
disposition_label(record.disposition),
record.external_result
));
}
print!("{output}");
Ok(())
}
/// Parse `kind:identifier` without making colons illegal in entity names.
fn parse_target(raw: &str) -> Result<(EntityType, EntityIdentifier), AppError> {
let (kind, identifier) = raw.split_once(':').ok_or_else(|| {
lib_efo::adjudication::AdjudicationError::Invalid(
"target must use KIND:IDENTIFIER, for example town:Haven".into(),
)
})?;
if identifier.is_empty() {
return Err(lib_efo::adjudication::AdjudicationError::Invalid(
"target identifier cannot be empty".into(),
)
.into());
}
let kind = match kind.to_ascii_lowercase().as_str() {
"character" | "chr" => EntityType::Character,
"town" => EntityType::Town,
"org" | "organization" | "organisation" => EntityType::Organization,
"calamity" => EntityType::Calamity,
"blocker" => EntityType::Blocker,
"event" => EntityType::Event,
_ => return Err(lib_efo::adjudication::AdjudicationError::Invalid(format!(
"unknown target kind `{kind}`; use character, town, org, calamity, blocker, or event"
))
.into()),
};
let identifier = if let Some(id) = identifier.strip_prefix('@') {
EntityIdentifier::Id(id.into())
} else {
EntityIdentifier::Name(identifier.into())
};
Ok((kind, identifier))
}
/// Parse one explicit effect.
fn parse_effect(raw: &str) -> Result<ChosenEffect, AppError> {
let (stat, delta) = raw.split_once(':').ok_or_else(|| {
lib_efo::adjudication::AdjudicationError::Invalid(format!(
"effect `{raw}` must use STAT:DELTA, for example health:-8"
))
})?;
let delta = isize::from_str(delta).map_err(|_| {
lib_efo::adjudication::AdjudicationError::Invalid(format!(
"effect `{raw}` has an invalid signed integer delta"
))
})?;
Ok(ChosenEffect {
stat: StatName::from_str(stat)?,
delta,
})
}
/// Stable lowercase label for a master-assigned level.
fn level_label(level: AdjudicationLevel) -> &'static str {
match level {
AdjudicationLevel::Excellent => "excellent",
AdjudicationLevel::Good => "good",
AdjudicationLevel::Mid => "mid",
AdjudicationLevel::Bad => "bad",
AdjudicationLevel::Worsen => "worsen",
AdjudicationLevel::Apocalypse => "apocalypse",
}
}
/// Stable lowercase label for a target disposition.
fn disposition_label(value: AdjudicationDisposition) -> &'static str {
match value {
AdjudicationDisposition::Applied => "applied",
AdjudicationDisposition::Dampened => "dampened",
AdjudicationDisposition::Avoided => "avoided",
AdjudicationDisposition::Destroyed => "destroyed",
}
}
/// Human-readable target-kind label.
fn target_type_label(value: EntityType) -> &'static str {
match value {
EntityType::Character => "character",
EntityType::Town => "town",
EntityType::Organization => "organisation",
EntityType::Calamity => "calamity",
EntityType::Blocker => "blocker",
EntityType::Event => "event",
EntityType::Player => "player",
}
}

View File

@ -6,6 +6,7 @@
#![warn(missing_docs, clippy::missing_docs_in_private_items)]
use lib_efo::{
adjudication::AdjudicationError,
error::{EpochError, StorageError},
repository_format::FormatError,
simulation::SimulationError,
@ -19,6 +20,9 @@ use thiserror::Error;
/// All errors that can bubble up to the CLI.
#[derive(Debug, Error, Diagnostic)]
pub enum AppError {
/// External-roll adjudication validation or application failed.
#[error("Adjudication stopped: {0}")]
Adjudication(#[from] AdjudicationError),
/// Generic “invalid command / missing flag” - emitted by clap.
#[error("Command-line error: {0}")]
// #[diagnostic(transparent)]

View File

@ -29,6 +29,7 @@ use clap::{Parser, Subcommand};
use crate::{
commands::{
adjudicate::AdjudicateCmd,
diffuse::DiffuseCmd,
entity_generic::EntitySubCommands,
epoch::cli_epoch::EpochCmd,
@ -73,6 +74,9 @@ struct Cli {
/// argument structure.
#[derive(Subcommand, Debug)]
enum TopLevelCmd {
/// Record and apply a player roll interpreted by the game master.
#[command(subcommand, visible_alias = "influx")]
Adjudicate(AdjudicateCmd),
/// Initialise a new epoch folder.
Init(InitCmd),
/// Recover an interrupted repository write.
@ -181,6 +185,7 @@ fn main() -> miette::Result<()> {
/// stdout and returned as a `miette::Result<()>`.
fn exec_dispatch(cli: Cli) -> Result<(), AppError> {
match cli.command {
TopLevelCmd::Adjudicate(cmd) => commands::adjudicate::handle(&cmd),
TopLevelCmd::Init(cmd) => commands::init::init(&cmd),
TopLevelCmd::Recover(cmd) => commands::safety::handle_recover(&cmd),
TopLevelCmd::Lock(cmd) => commands::safety::handle_lock(&cmd),

View File

@ -83,6 +83,8 @@ fn help_version_and_invalid_invocations_follow_cli_conventions() {
&["recover", "--help"][..],
&["lock", "--help"][..],
&["gen", "event", "--help"][..],
&["adjudicate", "--help"][..],
&["influx", "preview", "--help"][..],
] {
let output = efo(&repo, args);
assert_success(&output);
@ -105,6 +107,111 @@ fn help_version_and_invalid_invocations_follow_cli_conventions() {
}
}
#[test]
fn external_adjudications_preview_apply_audit_and_restore() {
let repo = TestRepo::new();
assert_success(&efo(&repo, &["init"]));
assert_success(&efo(&repo, &["event", "add", "Ashfall"]));
assert_success(&efo(
&repo,
&["town", "add", "Haven", "--stats", "health:40"],
));
assert_success(&efo(&repo, &["stage", "--all"]));
assert_success(&efo(&repo, &["commit", "-m", "Create test world"]));
let before = snapshot(&repo, 0);
let preview = efo(
&repo,
&[
"influx",
"preview",
"Ash",
"--target",
"town:Hav",
"--level",
"bad",
"--result",
"d20=4",
"--disposition",
"dampened",
"--effect",
"health:-8",
"--note",
"The ash reaches the wells",
],
);
assert_success(&preview);
let preview_text = stdout(&preview);
assert!(preview_text.contains("External result: d20=4"));
assert!(preview_text.contains("Health: 40 → 36 (-4)"));
assert!(preview_text.contains("Nothing changed"));
assert_eq!(snapshot(&repo, 0), before);
let apply = efo(
&repo,
&[
"adjudicate",
"apply",
"Ashfall",
"--target",
"town:Haven",
"--level",
"bad",
"--result",
"d20=4",
"--disposition",
"dampened",
"--effect",
"health:-8",
"--note",
"The ash reaches the wells",
],
);
assert_success(&apply);
assert!(stdout(&apply).contains("Undo: efo restore --worktree --all"));
assert_eq!(
snapshot(&repo, 0)["adjudications"]
.as_object()
.expect("adjudication records")
.len(),
1
);
let list = efo(&repo, &["adjudicate", "list", "Ashfall"]);
assert_success(&list);
assert!(stdout(&list).contains("d20=4"));
assert!(stdout(&list).contains("dampened"));
let duplicate = efo(
&repo,
&[
"adjudicate",
"apply",
"Ashfall",
"--target",
"town:Haven",
"--level",
"bad",
"--result",
"d20=4",
"--disposition",
"dampened",
"--effect",
"health:-8",
"--note",
"The ash reaches the wells",
],
);
assert!(!duplicate.status.success());
assert!(
stderr(&duplicate).contains("changed after preview")
|| stderr(&duplicate).contains("already recorded")
);
assert_success(&efo(&repo, &["restore", "--worktree", "--all"]));
assert_eq!(snapshot(&repo, 0), before);
}
#[test]
fn commands_outside_a_repository_return_actionable_errors() {
let repo = TestRepo::new();

View File

@ -129,6 +129,26 @@ previewing the same tick again cannot reach a town twice. Expired state remains
inspectable and can be restored, staged, or committed like any other worktree
change.
## External rolls and game-master adjudication
Epoch Forge does not roll or infer an outcome. The player rolls outside the
tool, then the game master records the result, interpretation, disposition,
and exact stat effects:
```text
efo adjudicate preview Plague --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-8
efo adjudicate apply Plague --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-8
efo adjudicate list Plague
```
`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
the worktree. Use `efo restore --worktree --all` to undo the ruling and its
effects together; audit records cannot be cleared independently from effects.
## Generation and output
`efo gen character|town|event|exotic|calamity|blocker` prints generated content

View File

@ -134,8 +134,7 @@ Proposed CLI:
efo adjudicate preview EVENT --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-20
efo adjudicate apply EVENT ...
efo adjudicate show EVENT
efo adjudicate clear EVENT [--yes]
efo adjudicate list [EVENT]
efo influx ... # visible legacy/domain alias
```
@ -144,10 +143,14 @@ the complete preview before its success line. `--result` is descriptive text,
not a value the program interprets. `--effect` is repeatable and always
explicit.
Target scopes support stable entity selectors and semantic groups (`towns`,
`characters`, `organisations`, `reached`) without requiring custom fields.
Ambiguous names abort. `reached` consumes the affected set of an event's
diffusion state.
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:
@ -276,8 +279,8 @@ upgrade path under issue #17.
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. Persist idempotent adjudication records and expose
preview/apply/show/clear.
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.
5. Add generic conflict state and pure round resolution.

View File

@ -10,8 +10,10 @@ use uuid::Uuid;
use crate::{
entity::Entity,
epoch::EpochInfo,
error::EpochError,
repository_format::FormatVersion,
stats::{ListStats, Modification, StatPair},
stats::{EntityType, ListStats, Modification, StatPair},
};
/// Configuration schema understood by this build.
@ -177,6 +179,9 @@ pub struct AdjudicationConfig {
/// Configuration, validation, or stale-application failure.
#[derive(Debug, thiserror::Error)]
pub enum AdjudicationError {
/// An entity referenced by the ruling does not exist.
#[error(transparent)]
Epoch(#[from] EpochError),
/// Reading an external policy failed.
#[error("cannot read adjudication config `{path}`: {source}")]
Io {
@ -204,6 +209,20 @@ pub enum AdjudicationError {
/// Stale target.
target: Uuid,
},
/// The same stable ruling has already been recorded.
#[error("adjudication @{record} is already recorded; nothing was changed")]
Duplicate {
/// Existing record identifier.
record: Uuid,
},
/// The world's record limit was reached.
#[error(
"adjudication record limit ({limit}) reached; commit or remove old records before retrying"
)]
RecordLimit {
/// Configured maximum.
limit: usize,
},
}
impl AdjudicationConfig {
@ -415,6 +434,64 @@ pub fn apply_to_target(
Ok(())
}
/// Atomically apply a preview to a cloned world and retain its audit record.
///
/// Callers should save the returned world through the repository transaction
/// layer. The input is left unchanged on every error.
pub fn apply_to_world(
world: &EpochInfo,
config: &AdjudicationConfig,
report: &AdjudicationReport,
target_type: EntityType,
) -> Result<EpochInfo, AdjudicationError> {
if world.adjudications.contains_key(&report.id) {
return Err(AdjudicationError::Duplicate { record: report.id });
}
if world.adjudications.len() >= config.max_records {
return Err(AdjudicationError::RecordLimit {
limit: config.max_records,
});
}
world.find_entity_strict(report.source, Some(EntityType::Event))?;
let mut updated = world.clone();
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());
Ok(updated)
}
/// Validate persisted audit-record references and structural invariants.
pub fn validate_adjudications(world: &EpochInfo) -> Result<(), AdjudicationError> {
for (key, report) in &world.adjudications {
if key != &report.id {
return Err(AdjudicationError::Invalid(format!(
"adjudication map key @{key} does not match record @{}",
report.id
)));
}
world.find_entity_strict(report.source, Some(EntityType::Event))?;
world.find_entity_strict(report.target, None)?;
let unique = report
.changes
.iter()
.map(|change| change.stat)
.collect::<HashSet<_>>();
if unique.len() != report.changes.len() {
return Err(AdjudicationError::Invalid(format!(
"record @{} changes one statistic more than once",
report.id
)));
}
if report.policy_id.trim().is_empty() {
return Err(AdjudicationError::Invalid(format!(
"record @{} has no policy identity",
report.id
)));
}
}
Ok(())
}
/// Validate a master-authored interpretation before previewing it.
fn validate_spec(
config: &AdjudicationConfig,

View File

@ -13,6 +13,7 @@ use std::fs::create_dir_all;
use uuid::Uuid;
use crate::{
adjudication::AdjudicationReport,
entity::{Entity, EntityIdentifier},
epoch::{
EpochId, SUB_NAME, SUBFOLDER_NAMING, TagList,
@ -96,6 +97,10 @@ pub struct EpochInfo {
#[serde(default)]
#[table(skip)]
pub diffusions: BTreeMap<Uuid, DiffusionState>,
/// Applied or recorded game-master adjudications, keyed by stable record ID.
#[serde(default)]
#[table(skip)]
pub adjudications: BTreeMap<Uuid, AdjudicationReport>,
}
impl Prettiable for EpochInfo {}
@ -118,6 +123,7 @@ impl Default for EpochInfo {
roads: Vec::new(),
mobility: BTreeMap::new(),
diffusions: BTreeMap::new(),
adjudications: BTreeMap::new(),
}
}
}

View File

@ -11,6 +11,7 @@ use serde::{Deserialize, Serialize};
use uuid::Uuid;
use crate::{
adjudication::validate_adjudications,
entity::EntityIdentifier,
epoch::{EntityIndex, EpochInfo},
repository_format::{FormatError, RepositoryManifest, RepositorySnapshot, decode_manifest},
@ -821,6 +822,7 @@ fn copy_world_metadata(source: &EpochInfo, destination: &mut EpochInfo) {
destination.rng_seed = source.rng_seed;
destination.tags = source.tags.clone();
destination.summary = source.summary.clone();
destination.adjudications = source.adjudications.clone();
}
/// Validate stable identity, collection type, and relationship targets.
@ -829,6 +831,8 @@ fn validate_world(label: &str, world: &EpochInfo) -> Result<(), WorkspaceError>
.and_then(|()| validate_mobility(world))
.and_then(|()| validate_diffusions(world))
.map_err(|error| WorkspaceError::Inconsistent(format!("{label} {error}")))?;
validate_adjudications(world)
.map_err(|error| WorkspaceError::Inconsistent(format!("{label} {error}")))?;
let index = EntityIndex::build(world);
if !index.duplicate_ids().is_empty() {
return Err(WorkspaceError::Inconsistent(format!(