feat: record external adjudications
This commit is contained in:
parent
9481146bce
commit
831c07b192
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
}
|
||||
}
|
||||
|
|
@ -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)]
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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!(
|
||||
|
|
|
|||
Loading…
Reference in New Issue