Struct Canwu 

pub struct Canwu { /* private fields */ }

Main in-process API. All returned world values are detached snapshots.

Implementations

impl Canwu

pub const fn version() -> &'static str

pub fn new(seed: u64, scenario: Scenario) -> Result<Self, CanwuError>

pub fn into_compacted(self) -> Result<CompactedCanwu, CanwuError>

Enters the explicit compact-journal interface without discarding evidence.

pub fn new_with_plugins( seed: u64, scenario: Scenario, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn new_with_manifest( seed: u64, scenario: Scenario, run_manifest: RunManifest, ) -> Result<Self, CanwuError>

pub fn new_with_manifest_and_plugins( seed: u64, scenario: Scenario, run_manifest: RunManifest, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn new_with_run_configuration( seed: u64, scenario: Scenario, run_manifest: RunManifest, run_configuration: RunConfiguration, ) -> Result<Self, CanwuError>

pub fn new_with_run_configuration_and_plugins( seed: u64, scenario: Scenario, run_manifest: RunManifest, run_configuration: RunConfiguration, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn demo(seed: u64) -> Result<Self, CanwuError>

Examples found in repository

examples/phased_boundary.rs (line 150)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    canwu.register_plugin(&SupplyPlugin)?;
    canwu.register_plugin(&DemandPlugin)?;

    let receipt = canwu
        .settle_boundary(BoundaryRequest::at(canwu.time()).with_cadence(SystemCadence::Daily))?;
    assert_eq!(receipt.allocations[0].granted, 6);
    assert_eq!(canwu.boundaries()[0].emissions.len(), 2);
    Ok(())
}

examples/plugin.rs (line 89)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();
    canwu.register_plugin(&StancePlugin)?;
    canwu.submit(CommandEnvelope::new(
        Issuer::Actor(ids.commander),
        Command::Plugin {
            plugin: "example-stance".to_owned(),
            command: "set_stance".to_owned(),
            payload: json!({ "army": ids.army, "stance": "hold" }),
        },
    ))?;
    Ok(())
}

examples/continuous_game_loop.rs (line 182)

    fn new(verbose: bool) -> Result<Self, CanwuError> {
        let authority = Canwu::demo(35)?;
        let ids = Canwu::demo_ids();
        let presentation = PresentationState::from_world(&authority.world(), ids.army);
        Ok(Self {
            authority,
            ids,
            presentation,
            accumulated_sim_nanos: 0,
            wall_elapsed: Duration::ZERO,
            frame: 0,
            reported_events: 0,
            next_progress_milestone: 25,
            canonical_boundaries: 0,
            verbose,
        })
    }

examples/decision_ticket.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    let replay_scenario = replay_scenario(&canwu);
    let ids = Canwu::demo_ids();

    open_aid_request(&mut canwu, ids)?;
    refresh_aid_options(&mut canwu, ids)?;
    resolve_aid_request(&mut canwu)?;

    let trace = canwu
        .decision_traces()
        .last()
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

    verify_persistence_and_replay(&canwu, replay_scenario)?;
    println!("snapshot_restore=ok exact_replay=ok");
    Ok(())
}

examples/move_army.rs (line 4)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

pub fn demo_ids() -> DemoIds

Examples found in repository

examples/plugin.rs (line 90)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();
    canwu.register_plugin(&StancePlugin)?;
    canwu.submit(CommandEnvelope::new(
        Issuer::Actor(ids.commander),
        Command::Plugin {
            plugin: "example-stance".to_owned(),
            command: "set_stance".to_owned(),
            payload: json!({ "army": ids.army, "stance": "hold" }),
        },
    ))?;
    Ok(())
}

examples/continuous_game_loop.rs (line 183)

    fn new(verbose: bool) -> Result<Self, CanwuError> {
        let authority = Canwu::demo(35)?;
        let ids = Canwu::demo_ids();
        let presentation = PresentationState::from_world(&authority.world(), ids.army);
        Ok(Self {
            authority,
            ids,
            presentation,
            accumulated_sim_nanos: 0,
            wall_elapsed: Duration::ZERO,
            frame: 0,
            reported_events: 0,
            next_progress_milestone: 25,
            canonical_boundaries: 0,
            verbose,
        })
    }

    fn run_phase(&mut self, phase: SpeedPhase, profile: FrameProfile) -> Result<(), CanwuError> {
        let mut remaining_millis = phase.wall_millis;
        let mut pattern_index = 0;
        let mut first_frame = true;

        while remaining_millis > 0 {
            let frame_millis = profile.frame_millis[pattern_index % profile.frame_millis.len()]
                .min(remaining_millis);
            remaining_millis -= frame_millis;
            self.render_frame(
                Duration::from_millis(frame_millis),
                phase.speed,
                first_frame || remaining_millis == 0,
            )?;
            first_frame = false;
            pattern_index += 1;
        }
        Ok(())
    }

    fn render_frame(
        &mut self,
        wall_dt: Duration,
        speed: GameSpeed,
        phase_edge: bool,
    ) -> Result<(), CanwuError> {
        self.frame += 1;
        self.wall_elapsed += wall_dt;

        let converted_wall_nanos = wall_dt.as_nanos() * BASE_SIM_SECONDS_PER_WALL_SECOND;
        self.accumulated_sim_nanos += converted_wall_nanos * speed.multiplier();

        let mut authority_changed = false;
        while self.accumulated_sim_nanos >= SIMULATION_MINUTE_NANOS {
            let receipts = self.authority.advance_canonical(SIMULATION_QUANTUM)?;
            self.canonical_boundaries += receipts.len();
            authority_changed |= !receipts.is_empty();
            self.accumulated_sim_nanos -= SIMULATION_MINUTE_NANOS;
        }

        if authority_changed {
            self.refresh_presentation_from_authority();
        }

        let progress = self.presentation.render(self.presentation_time());
        let crossed_milestone = self.crossed_progress_milestone(progress);
        let has_new_events = self.reported_events < self.authority.events().len();

        if self.verbose && (phase_edge || crossed_milestone || has_new_events) {
            self.print_frame(speed);
        }
        self.report_new_events();
        Ok(())
    }

    /// This host never backdates mid-quantum input. It deterministically rounds
    /// up to the next representable Canwu minute; another host may choose a
    /// different policy, but it must apply the same policy across render FPS.
    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

    fn refresh_presentation_from_authority(&mut self) {
        self.presentation
            .refresh_from_authority(&self.authority.world(), self.ids.army);
    }

    fn presentation_time(&self) -> PresentationTime {
        PresentationTime {
            canonical: self.authority.time(),
            sub_minute: Duration::from_nanos(
                u64::try_from(self.accumulated_sim_nanos)
                    .expect("the sub-minute accumulator must fit a Duration"),
            ),
        }
    }

    fn crossed_progress_milestone(&mut self, progress: Option<f64>) -> bool {
        let Some(progress) = progress else {
            return false;
        };
        let mut crossed = false;
        while self.next_progress_milestone <= 100
            && progress * 100.0 + f64::EPSILON >= f64::from(self.next_progress_milestone)
        {
            crossed = true;
            self.next_progress_milestone += 25;
        }
        crossed
    }

    fn print_frame(&self, speed: GameSpeed) {
        println!(
            "frame={:>5} speed={:<6} wall={:>7.3}s visual_time={} canwu_time={} {}",
            self.frame,
            speed.label(),
            self.wall_elapsed.as_secs_f64(),
            self.presentation_time(),
            self.authority.time(),
            self.presentation.describe(),
        );
    }

    fn report_new_events(&mut self) {
        let events = self.authority.events();
        if self.verbose {
            for event in &events[self.reported_events..] {
                println!(
                    "EVENT: at={} type={} {}",
                    event.timestamp,
                    event.kind.qualified_event_type(),
                    event.summary,
                );
            }
        }
        self.reported_events = events.len();
    }

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }
}

struct RunOutcome {
    profile: &'static str,
    frames: u64,
    time: SimTime,
    world: WorldSnapshot,
    events: Vec<SimEvent>,
    commands: Vec<CommandRecord>,
    authoritative_state_hash: String,
    checkpoint_hash: String,
    canonical_boundaries: usize,
}

fn run(profile: FrameProfile, verbose: bool) -> Result<RunOutcome, CanwuError> {
    let mut host = GameHost::new(verbose)?;
    if verbose {
        println!("\n{} render loop", profile.name);
    }

    host.run_phase(SPEED_SCHEDULE[0], profile)?;
    host.submit_player_command()?;
    host.run_phase(SPEED_SCHEDULE[1], profile)?;
    host.run_phase(SPEED_SCHEDULE[2], profile)?;

    let time_before_pause = host.authority.time();
    let remainder_before_pause = host.accumulated_sim_nanos;
    let presentation_before_pause = host.presentation_time();
    let frames_before_pause = host.frame;
    assert!(
        remainder_before_pause > 0,
        "the pause fixture must preserve a fractional simulation minute"
    );
    host.run_phase(SPEED_SCHEDULE[3], profile)?;
    assert!(
        host.frame > frames_before_pause,
        "pause must keep rendering"
    );
    assert_eq!(
        host.authority.time(),
        time_before_pause,
        "pause must not advance Canwu"
    );
    assert_eq!(
        host.accumulated_sim_nanos, remainder_before_pause,
        "pause must not add desired simulation time"
    );
    assert_eq!(
        host.presentation_time(),
        presentation_before_pause,
        "pause must freeze presentation time"
    );

    host.run_phase(SPEED_SCHEDULE[4], profile)?;
    assert_eq!(
        host.accumulated_sim_nanos, 0,
        "the scripted schedule should end on a simulation-minute boundary"
    );
    host.outcome(profile)
}

fn std_duration(duration: SimDuration) -> Duration {
    let minutes = u64::try_from(duration.as_minutes())
        .expect("presentation interpolation requires a non-negative duration");
    Duration::from_secs(
        minutes
            .checked_mul(60)
            .expect("presentation duration must remain representable"),
    )
}

fn assert_fps_independent(left: &RunOutcome, right: &RunOutcome) {
    assert_ne!(
        left.frames, right.frames,
        "the render segmentations must differ"
    );
    assert_eq!(left.time, right.time, "Canwu time changed with render FPS");
    assert_eq!(
        left.world, right.world,
        "world state changed with render FPS"
    );
    assert_eq!(left.events, right.events, "events changed with render FPS");
    assert_eq!(
        left.commands, right.commands,
        "command ordering changed with render FPS"
    );
    assert_eq!(
        left.authoritative_state_hash, right.authoritative_state_hash,
        "authoritative state hash changed with render FPS"
    );
    assert_eq!(
        left.checkpoint_hash, right.checkpoint_hash,
        "checkpoint hash changed with render FPS"
    );
    assert_eq!(
        left.canonical_boundaries, right.canonical_boundaries,
        "canonical boundary count changed with render FPS"
    );
}

fn assert_expected_outcome(outcome: &RunOutcome) {
    let ids = Canwu::demo_ids();
    let command_at = SimTime::from_minutes(1);
    let arrival_at = SimTime::from_minutes(1_081);
    let final_time = SimTime::from_minutes(1_082);

    assert_eq!(outcome.time, final_time, "the scripted final time changed");
    let army = outcome
        .world
        .army(ids.army)
        .expect("the demo army must remain present");
    assert_eq!(
        army.location, ids.eastern_territory,
        "the scheduled arrival must execute"
    );
    assert!(
        army.transit.is_none(),
        "the army must no longer be in authoritative transit"
    );

    assert_eq!(
        outcome.commands.len(),
        1,
        "the move command must be accepted"
    );
    let command = &outcome.commands[0];
    assert_eq!(command.accepted_at, command_at);
    assert_eq!(command.envelope.expected_time, Some(command_at));
    assert!(matches!(
        &command.envelope.command,
        Command::OrderMovement {
            subject: EntityRef::Army(army),
            destination,
            cargo,
        } if *army == ids.army
            && *destination == ids.eastern_territory
            && cargo.is_empty()
    ));

    let event_timeline = outcome
        .events
        .iter()
        .map(|event| (event.kind.qualified_event_type(), event.timestamp))
        .collect::<Vec<_>>();
    assert_eq!(
        event_timeline,
        vec![
            ("move_ordered".to_owned(), command_at),
            ("army_arrived".to_owned(), arrival_at),
            ("knowledge_updated".to_owned(), arrival_at),
            ("report_dispatched".to_owned(), arrival_at),
        ],
        "the expected command and scheduled-arrival event timeline changed"
    );
    assert_eq!(
        outcome.canonical_boundaries, 2,
        "the command and arrival should settle at two canonical boundaries"
    );
}

examples/decision_ticket.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    let replay_scenario = replay_scenario(&canwu);
    let ids = Canwu::demo_ids();

    open_aid_request(&mut canwu, ids)?;
    refresh_aid_options(&mut canwu, ids)?;
    resolve_aid_request(&mut canwu)?;

    let trace = canwu
        .decision_traces()
        .last()
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

    verify_persistence_and_replay(&canwu, replay_scenario)?;
    println!("snapshot_restore=ok exact_replay=ok");
    Ok(())
}

examples/move_army.rs (line 5)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

pub const fn time(&self) -> SimTime

Examples found in repository

examples/phased_boundary.rs (line 155)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    canwu.register_plugin(&SupplyPlugin)?;
    canwu.register_plugin(&DemandPlugin)?;

    let receipt = canwu
        .settle_boundary(BoundaryRequest::at(canwu.time()).with_cadence(SystemCadence::Daily))?;
    assert_eq!(receipt.allocations[0].granted, 6);
    assert_eq!(canwu.boundaries()[0].emissions.len(), 2);
    Ok(())
}

examples/move_army.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

examples/continuous_game_loop.rs (line 260)

    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

    fn refresh_presentation_from_authority(&mut self) {
        self.presentation
            .refresh_from_authority(&self.authority.world(), self.ids.army);
    }

    fn presentation_time(&self) -> PresentationTime {
        PresentationTime {
            canonical: self.authority.time(),
            sub_minute: Duration::from_nanos(
                u64::try_from(self.accumulated_sim_nanos)
                    .expect("the sub-minute accumulator must fit a Duration"),
            ),
        }
    }

    fn crossed_progress_milestone(&mut self, progress: Option<f64>) -> bool {
        let Some(progress) = progress else {
            return false;
        };
        let mut crossed = false;
        while self.next_progress_milestone <= 100
            && progress * 100.0 + f64::EPSILON >= f64::from(self.next_progress_milestone)
        {
            crossed = true;
            self.next_progress_milestone += 25;
        }
        crossed
    }

    fn print_frame(&self, speed: GameSpeed) {
        println!(
            "frame={:>5} speed={:<6} wall={:>7.3}s visual_time={} canwu_time={} {}",
            self.frame,
            speed.label(),
            self.wall_elapsed.as_secs_f64(),
            self.presentation_time(),
            self.authority.time(),
            self.presentation.describe(),
        );
    }

    fn report_new_events(&mut self) {
        let events = self.authority.events();
        if self.verbose {
            for event in &events[self.reported_events..] {
                println!(
                    "EVENT: at={} type={} {}",
                    event.timestamp,
                    event.kind.qualified_event_type(),
                    event.summary,
                );
            }
        }
        self.reported_events = events.len();
    }

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }
}

struct RunOutcome {
    profile: &'static str,
    frames: u64,
    time: SimTime,
    world: WorldSnapshot,
    events: Vec<SimEvent>,
    commands: Vec<CommandRecord>,
    authoritative_state_hash: String,
    checkpoint_hash: String,
    canonical_boundaries: usize,
}

fn run(profile: FrameProfile, verbose: bool) -> Result<RunOutcome, CanwuError> {
    let mut host = GameHost::new(verbose)?;
    if verbose {
        println!("\n{} render loop", profile.name);
    }

    host.run_phase(SPEED_SCHEDULE[0], profile)?;
    host.submit_player_command()?;
    host.run_phase(SPEED_SCHEDULE[1], profile)?;
    host.run_phase(SPEED_SCHEDULE[2], profile)?;

    let time_before_pause = host.authority.time();
    let remainder_before_pause = host.accumulated_sim_nanos;
    let presentation_before_pause = host.presentation_time();
    let frames_before_pause = host.frame;
    assert!(
        remainder_before_pause > 0,
        "the pause fixture must preserve a fractional simulation minute"
    );
    host.run_phase(SPEED_SCHEDULE[3], profile)?;
    assert!(
        host.frame > frames_before_pause,
        "pause must keep rendering"
    );
    assert_eq!(
        host.authority.time(),
        time_before_pause,
        "pause must not advance Canwu"
    );
    assert_eq!(
        host.accumulated_sim_nanos, remainder_before_pause,
        "pause must not add desired simulation time"
    );
    assert_eq!(
        host.presentation_time(),
        presentation_before_pause,
        "pause must freeze presentation time"
    );

    host.run_phase(SPEED_SCHEDULE[4], profile)?;
    assert_eq!(
        host.accumulated_sim_nanos, 0,
        "the scripted schedule should end on a simulation-minute boundary"
    );
    host.outcome(profile)
}

examples/decision_ticket.rs (line 42)

fn open_aid_request(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    let now = canwu.time();
    let controller = DecisionControllerBinding::new(
        "warlord-b-ai",
        DecisionPolicyIdentity::new(DecisionPolicyKind::Utility, "aid-utility", "1"),
        DecisionAuthority::Actor {
            actor: ids.commander,
        },
    )
    .with_command_subject(EntityRef::Army(ids.army));

    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(1),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(2),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: DecisionTicketId::new(1),
                    definition: "beiyang.request-military-aid".to_owned(),
                    decision_maker: EntityRef::Person(ids.commander),
                    assigned_controller: "warlord-b-ai".to_owned(),
                    summary: "Neighboring warlord requests immediate military aid".to_owned(),
                    context: DecisionContext::new(
                        "beiyang.aid-request.v1",
                        json!({
                            "requester": "warlord-a",
                            "battle": "ongoing-front",
                            "common_enemy": true
                        }),
                    ),
                    options: vec![DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    }],
                    deadline: Some(now + SimDuration::days(2)),
                },
            },
        ),
    )?;
    canwu.step_canonical()?.expect("decision intake boundary");
    Ok(())
}

fn refresh_aid_options(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    canwu.enqueue_decision(
        canwu.time(),
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(3),
            canwu.revision(),
            DecisionMutation::ReplaceOptions {
                ticket_id: DecisionTicketId::new(1),
                expected_version: 1,
                context: DecisionContext::new(
                    "beiyang.aid-request.v1",
                    json!({
                        "requester": "warlord-a",
                        "battle": "ongoing-front",
                        "common_enemy": true,
                        "route_confirmed": true
                    }),
                ),
                options: vec![
                    DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    },
                    DecisionOption {
                        action: DecisionAction::Command {
                            command: serde_json::to_value(Command::OrderMovement {
                                subject: EntityRef::Army(ids.army),
                                destination: ids.eastern_territory,
                                cargo: Vec::new(),
                            })?,
                        },
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), -20),
                            ("alliance".to_owned(), 90),
                        ]),
                        ..DecisionOption::new("send-aid", "Send the neighboring army")
                    },
                ],
            },
        ),
    )?;
    canwu
        .step_canonical()?
        .expect("dynamic option refresh boundary");
    Ok(())
}

fn resolve_aid_request(canwu: &mut Canwu) -> Result<(), Box<dyn std::error::Error>> {
    let policy = WeightedUtilityPolicy::new(
        "aid-utility",
        "1",
        UtilityProfile {
            weights: BTreeMap::from([("alliance".to_owned(), 3), ("home_defense".to_owned(), 1)]),
        },
    );
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(4),
        Some(CommandRequestId::new(1)),
        DecisionTicketId::new(1),
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu
        .step_canonical()?
        .expect("decision resolution boundary");
    Ok(())
}

pub const fn run_manifest(&self) -> &RunManifest

pub const fn run_configuration(&self) -> &RunConfigurationSnapshot

pub fn revision(&self) -> u64

Returns the persisted authoritative transaction revision.

Accepted commands, persisted expected rejections, and completed settlement boundaries each advance it exactly once. Failed work, exact retries, bare clock movement, queued but unadmitted ingress, and plugin setup do not advance it; combine it with command expected-time guards.

Examples found in repository

examples/continuous_game_loop.rs (line 278)

    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

examples/decision_ticket.rs (line 57)

fn open_aid_request(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    let now = canwu.time();
    let controller = DecisionControllerBinding::new(
        "warlord-b-ai",
        DecisionPolicyIdentity::new(DecisionPolicyKind::Utility, "aid-utility", "1"),
        DecisionAuthority::Actor {
            actor: ids.commander,
        },
    )
    .with_command_subject(EntityRef::Army(ids.army));

    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(1),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(2),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: DecisionTicketId::new(1),
                    definition: "beiyang.request-military-aid".to_owned(),
                    decision_maker: EntityRef::Person(ids.commander),
                    assigned_controller: "warlord-b-ai".to_owned(),
                    summary: "Neighboring warlord requests immediate military aid".to_owned(),
                    context: DecisionContext::new(
                        "beiyang.aid-request.v1",
                        json!({
                            "requester": "warlord-a",
                            "battle": "ongoing-front",
                            "common_enemy": true
                        }),
                    ),
                    options: vec![DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    }],
                    deadline: Some(now + SimDuration::days(2)),
                },
            },
        ),
    )?;
    canwu.step_canonical()?.expect("decision intake boundary");
    Ok(())
}

fn refresh_aid_options(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    canwu.enqueue_decision(
        canwu.time(),
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(3),
            canwu.revision(),
            DecisionMutation::ReplaceOptions {
                ticket_id: DecisionTicketId::new(1),
                expected_version: 1,
                context: DecisionContext::new(
                    "beiyang.aid-request.v1",
                    json!({
                        "requester": "warlord-a",
                        "battle": "ongoing-front",
                        "common_enemy": true,
                        "route_confirmed": true
                    }),
                ),
                options: vec![
                    DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    },
                    DecisionOption {
                        action: DecisionAction::Command {
                            command: serde_json::to_value(Command::OrderMovement {
                                subject: EntityRef::Army(ids.army),
                                destination: ids.eastern_territory,
                                cargo: Vec::new(),
                            })?,
                        },
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), -20),
                            ("alliance".to_owned(), 90),
                        ]),
                        ..DecisionOption::new("send-aid", "Send the neighboring army")
                    },
                ],
            },
        ),
    )?;
    canwu
        .step_canonical()?
        .expect("dynamic option refresh boundary");
    Ok(())
}

pub fn run_manifest_hash(&self) -> &str

pub fn checkpoint_hash(&self) -> &str

Examples found in repository

examples/continuous_game_loop.rs (line 369)

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }

pub fn authoritative_state_hash(&self) -> Result<String, CanwuError>

Examples found in repository

examples/continuous_game_loop.rs (line 368)

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }

pub fn world(&self) -> WorldSnapshot

Examples found in repository

examples/continuous_game_loop.rs (line 184)

    fn new(verbose: bool) -> Result<Self, CanwuError> {
        let authority = Canwu::demo(35)?;
        let ids = Canwu::demo_ids();
        let presentation = PresentationState::from_world(&authority.world(), ids.army);
        Ok(Self {
            authority,
            ids,
            presentation,
            accumulated_sim_nanos: 0,
            wall_elapsed: Duration::ZERO,
            frame: 0,
            reported_events: 0,
            next_progress_milestone: 25,
            canonical_boundaries: 0,
            verbose,
        })
    }

    fn run_phase(&mut self, phase: SpeedPhase, profile: FrameProfile) -> Result<(), CanwuError> {
        let mut remaining_millis = phase.wall_millis;
        let mut pattern_index = 0;
        let mut first_frame = true;

        while remaining_millis > 0 {
            let frame_millis = profile.frame_millis[pattern_index % profile.frame_millis.len()]
                .min(remaining_millis);
            remaining_millis -= frame_millis;
            self.render_frame(
                Duration::from_millis(frame_millis),
                phase.speed,
                first_frame || remaining_millis == 0,
            )?;
            first_frame = false;
            pattern_index += 1;
        }
        Ok(())
    }

    fn render_frame(
        &mut self,
        wall_dt: Duration,
        speed: GameSpeed,
        phase_edge: bool,
    ) -> Result<(), CanwuError> {
        self.frame += 1;
        self.wall_elapsed += wall_dt;

        let converted_wall_nanos = wall_dt.as_nanos() * BASE_SIM_SECONDS_PER_WALL_SECOND;
        self.accumulated_sim_nanos += converted_wall_nanos * speed.multiplier();

        let mut authority_changed = false;
        while self.accumulated_sim_nanos >= SIMULATION_MINUTE_NANOS {
            let receipts = self.authority.advance_canonical(SIMULATION_QUANTUM)?;
            self.canonical_boundaries += receipts.len();
            authority_changed |= !receipts.is_empty();
            self.accumulated_sim_nanos -= SIMULATION_MINUTE_NANOS;
        }

        if authority_changed {
            self.refresh_presentation_from_authority();
        }

        let progress = self.presentation.render(self.presentation_time());
        let crossed_milestone = self.crossed_progress_milestone(progress);
        let has_new_events = self.reported_events < self.authority.events().len();

        if self.verbose && (phase_edge || crossed_milestone || has_new_events) {
            self.print_frame(speed);
        }
        self.report_new_events();
        Ok(())
    }

    /// This host never backdates mid-quantum input. It deterministically rounds
    /// up to the next representable Canwu minute; another host may choose a
    /// different policy, but it must apply the same policy across render FPS.
    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

    fn refresh_presentation_from_authority(&mut self) {
        self.presentation
            .refresh_from_authority(&self.authority.world(), self.ids.army);
    }

    fn presentation_time(&self) -> PresentationTime {
        PresentationTime {
            canonical: self.authority.time(),
            sub_minute: Duration::from_nanos(
                u64::try_from(self.accumulated_sim_nanos)
                    .expect("the sub-minute accumulator must fit a Duration"),
            ),
        }
    }

    fn crossed_progress_milestone(&mut self, progress: Option<f64>) -> bool {
        let Some(progress) = progress else {
            return false;
        };
        let mut crossed = false;
        while self.next_progress_milestone <= 100
            && progress * 100.0 + f64::EPSILON >= f64::from(self.next_progress_milestone)
        {
            crossed = true;
            self.next_progress_milestone += 25;
        }
        crossed
    }

    fn print_frame(&self, speed: GameSpeed) {
        println!(
            "frame={:>5} speed={:<6} wall={:>7.3}s visual_time={} canwu_time={} {}",
            self.frame,
            speed.label(),
            self.wall_elapsed.as_secs_f64(),
            self.presentation_time(),
            self.authority.time(),
            self.presentation.describe(),
        );
    }

    fn report_new_events(&mut self) {
        let events = self.authority.events();
        if self.verbose {
            for event in &events[self.reported_events..] {
                println!(
                    "EVENT: at={} type={} {}",
                    event.timestamp,
                    event.kind.qualified_event_type(),
                    event.summary,
                );
            }
        }
        self.reported_events = events.len();
    }

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }

pub fn knowledge(&self) -> &KnowledgeSnapshot

Trusted host/admin access to the complete knowledge snapshot.

Do not expose this facade to player, agent, observer, or remote clients; use Canwu::viewer or Canwu::viewer_for_actor instead.

pub fn events(&self) -> &[SimEvent]

Examples found in repository

examples/continuous_game_loop.rs (line 245)

    fn render_frame(
        &mut self,
        wall_dt: Duration,
        speed: GameSpeed,
        phase_edge: bool,
    ) -> Result<(), CanwuError> {
        self.frame += 1;
        self.wall_elapsed += wall_dt;

        let converted_wall_nanos = wall_dt.as_nanos() * BASE_SIM_SECONDS_PER_WALL_SECOND;
        self.accumulated_sim_nanos += converted_wall_nanos * speed.multiplier();

        let mut authority_changed = false;
        while self.accumulated_sim_nanos >= SIMULATION_MINUTE_NANOS {
            let receipts = self.authority.advance_canonical(SIMULATION_QUANTUM)?;
            self.canonical_boundaries += receipts.len();
            authority_changed |= !receipts.is_empty();
            self.accumulated_sim_nanos -= SIMULATION_MINUTE_NANOS;
        }

        if authority_changed {
            self.refresh_presentation_from_authority();
        }

        let progress = self.presentation.render(self.presentation_time());
        let crossed_milestone = self.crossed_progress_milestone(progress);
        let has_new_events = self.reported_events < self.authority.events().len();

        if self.verbose && (phase_edge || crossed_milestone || has_new_events) {
            self.print_frame(speed);
        }
        self.report_new_events();
        Ok(())
    }

    /// This host never backdates mid-quantum input. It deterministically rounds
    /// up to the next representable Canwu minute; another host may choose a
    /// different policy, but it must apply the same policy across render FPS.
    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

    fn refresh_presentation_from_authority(&mut self) {
        self.presentation
            .refresh_from_authority(&self.authority.world(), self.ids.army);
    }

    fn presentation_time(&self) -> PresentationTime {
        PresentationTime {
            canonical: self.authority.time(),
            sub_minute: Duration::from_nanos(
                u64::try_from(self.accumulated_sim_nanos)
                    .expect("the sub-minute accumulator must fit a Duration"),
            ),
        }
    }

    fn crossed_progress_milestone(&mut self, progress: Option<f64>) -> bool {
        let Some(progress) = progress else {
            return false;
        };
        let mut crossed = false;
        while self.next_progress_milestone <= 100
            && progress * 100.0 + f64::EPSILON >= f64::from(self.next_progress_milestone)
        {
            crossed = true;
            self.next_progress_milestone += 25;
        }
        crossed
    }

    fn print_frame(&self, speed: GameSpeed) {
        println!(
            "frame={:>5} speed={:<6} wall={:>7.3}s visual_time={} canwu_time={} {}",
            self.frame,
            speed.label(),
            self.wall_elapsed.as_secs_f64(),
            self.presentation_time(),
            self.authority.time(),
            self.presentation.describe(),
        );
    }

    fn report_new_events(&mut self) {
        let events = self.authority.events();
        if self.verbose {
            for event in &events[self.reported_events..] {
                println!(
                    "EVENT: at={} type={} {}",
                    event.timestamp,
                    event.kind.qualified_event_type(),
                    event.summary,
                );
            }
        }
        self.reported_events = events.len();
    }

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }

pub fn commands(&self) -> &[CommandRecord]

Examples found in repository

examples/continuous_game_loop.rs (line 367)

    fn outcome(self, profile: FrameProfile) -> Result<RunOutcome, CanwuError> {
        Ok(RunOutcome {
            profile: profile.name,
            frames: self.frame,
            time: self.authority.time(),
            world: self.authority.world(),
            events: self.authority.events().to_vec(),
            commands: self.authority.commands().to_vec(),
            authoritative_state_hash: self.authority.authoritative_state_hash()?,
            checkpoint_hash: self.authority.checkpoint_hash().to_owned(),
            canonical_boundaries: self.canonical_boundaries,
        })
    }

pub fn boundaries(&self) -> &[BoundaryRecord]

Examples found in repository

examples/phased_boundary.rs (line 157)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    canwu.register_plugin(&SupplyPlugin)?;
    canwu.register_plugin(&DemandPlugin)?;

    let receipt = canwu
        .settle_boundary(BoundaryRequest::at(canwu.time()).with_cadence(SystemCadence::Daily))?;
    assert_eq!(receipt.allocations[0].granted, 6);
    assert_eq!(canwu.boundaries()[0].emissions.len(), 2);
    Ok(())
}

pub fn command_attempts(&self) -> &[CommandAttemptRecord]

pub fn ingress_log(&self) -> &[IngressRecord]

pub fn domain_record( &self, reference: &DomainRecordRef, ) -> Option<&DomainRecord>

pub fn typed_domain_record<T: DomainRecordType>( &self, reference: &TypedDomainRecordRef<T>, ) -> Option<&DomainRecord>

pub fn domain_records(&self) -> impl Iterator<Item = &DomainRecord>

pub const fn decision_state(&self) -> &DecisionState

pub fn decision_ticket(&self, id: DecisionTicketId) -> Option<&DecisionTicket>

pub fn decision_traces(&self) -> &[DecisionTrace]

Examples found in repository

examples/decision_ticket.rs (line 21)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    let replay_scenario = replay_scenario(&canwu);
    let ids = Canwu::demo_ids();

    open_aid_request(&mut canwu, ids)?;
    refresh_aid_options(&mut canwu, ids)?;
    resolve_aid_request(&mut canwu)?;

    let trace = canwu
        .decision_traces()
        .last()
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

    verify_persistence_and_replay(&canwu, replay_scenario)?;
    println!("snapshot_restore=ok exact_replay=ok");
    Ok(())
}

pub fn decision_attempts(&self) -> &[DecisionAttemptRecord]

pub fn random_draws(&self) -> &[RandomDrawRecord]

pub fn boundary_head_hash(&self) -> Option<&str>

pub const fn schema(&self) -> &SchemaRegistry

pub fn plugin_descriptors(&self) -> impl Iterator<Item = &PluginDescriptor>

pub fn replay_journal(&self) -> ReplayJournal

Examples found in repository

examples/decision_ticket.rs (line 181)

fn verify_persistence_and_replay(
    canwu: &Canwu,
    replay_scenario: Scenario,
) -> Result<(), Box<dyn std::error::Error>> {
    let snapshot = canwu.snapshot();
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), snapshot);
    let replayed = Canwu::replay_from_journal(replay_scenario, &[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), snapshot);
    Ok(())
}

pub fn evidence_cursor(&self) -> Result<EvidenceCursor, CanwuError>

pub fn checkpoint(&self) -> Result<SimulationCheckpoint, CanwuError>

pub fn journal_segment_since( &self, start: EvidenceCursor, ) -> Result<EvidenceJournalSegment, CanwuError>

pub fn checkpoint_journal(&self) -> Result<CheckpointJournal, CanwuError>

pub fn checkpoint_journal_json(&self) -> Result<String, CanwuError>

pub fn register_plugin<P: SimulationPlugin + ?Sized>( &mut self, plugin: &P, ) -> Result<(), CanwuError>

Examples found in repository

examples/phased_boundary.rs (line 151)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    canwu.register_plugin(&SupplyPlugin)?;
    canwu.register_plugin(&DemandPlugin)?;

    let receipt = canwu
        .settle_boundary(BoundaryRequest::at(canwu.time()).with_cadence(SystemCadence::Daily))?;
    assert_eq!(receipt.allocations[0].granted, 6);
    assert_eq!(canwu.boundaries()[0].emissions.len(), 2);
    Ok(())
}

examples/plugin.rs (line 91)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();
    canwu.register_plugin(&StancePlugin)?;
    canwu.submit(CommandEnvelope::new(
        Issuer::Actor(ids.commander),
        Command::Plugin {
            plugin: "example-stance".to_owned(),
            command: "set_stance".to_owned(),
            payload: json!({ "army": ids.army, "stance": "hold" }),
        },
    ))?;
    Ok(())
}

pub fn submit( &mut self, command: CommandEnvelope, ) -> Result<CommandReceipt, CanwuError>

Examples found in repository

examples/plugin.rs (lines 92-99)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();
    canwu.register_plugin(&StancePlugin)?;
    canwu.submit(CommandEnvelope::new(
        Issuer::Actor(ids.commander),
        Command::Plugin {
            plugin: "example-stance".to_owned(),
            command: "set_stance".to_owned(),
            payload: json!({ "army": ids.army, "stance": "hold" }),
        },
    ))?;
    Ok(())
}

pub fn process_command( &mut self, request: CommandRequest, ) -> Result<CommandOutcome, CanwuError>

pub fn enqueue_command( &mut self, due_at: SimTime, priority: i32, request: CommandRequest, ) -> Result<IngressReceipt, CanwuError>

Examples found in repository

examples/continuous_game_loop.rs (line 281)

    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

pub fn enqueue_plugin_ingress( &mut self, request: PluginIngressRequest, ) -> Result<IngressReceipt, CanwuError>

pub fn prepare_decision( &self, decision_request_id: DecisionRequestId, command_request_id: Option<CommandRequestId>, ticket_id: DecisionTicketId, policy: &dyn DecisionPolicy, ) -> Result<DecisionEvaluation, CanwuError>

pub fn prepare_decision_at( &self, due_at: SimTime, decision_request_id: DecisionRequestId, command_request_id: Option<CommandRequestId>, ticket_id: DecisionTicketId, policy: &dyn DecisionPolicy, ) -> Result<DecisionEvaluation, CanwuError>

pub fn enqueue_decision( &mut self, due_at: SimTime, priority: i32, request: DecisionIngressRequest, ) -> Result<IngressReceipt, CanwuError>

Examples found in repository

examples/decision_ticket.rs (lines 52-60)

fn open_aid_request(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    let now = canwu.time();
    let controller = DecisionControllerBinding::new(
        "warlord-b-ai",
        DecisionPolicyIdentity::new(DecisionPolicyKind::Utility, "aid-utility", "1"),
        DecisionAuthority::Actor {
            actor: ids.commander,
        },
    )
    .with_command_subject(EntityRef::Army(ids.army));

    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(1),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(2),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: DecisionTicketId::new(1),
                    definition: "beiyang.request-military-aid".to_owned(),
                    decision_maker: EntityRef::Person(ids.commander),
                    assigned_controller: "warlord-b-ai".to_owned(),
                    summary: "Neighboring warlord requests immediate military aid".to_owned(),
                    context: DecisionContext::new(
                        "beiyang.aid-request.v1",
                        json!({
                            "requester": "warlord-a",
                            "battle": "ongoing-front",
                            "common_enemy": true
                        }),
                    ),
                    options: vec![DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    }],
                    deadline: Some(now + SimDuration::days(2)),
                },
            },
        ),
    )?;
    canwu.step_canonical()?.expect("decision intake boundary");
    Ok(())
}

fn refresh_aid_options(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    canwu.enqueue_decision(
        canwu.time(),
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(3),
            canwu.revision(),
            DecisionMutation::ReplaceOptions {
                ticket_id: DecisionTicketId::new(1),
                expected_version: 1,
                context: DecisionContext::new(
                    "beiyang.aid-request.v1",
                    json!({
                        "requester": "warlord-a",
                        "battle": "ongoing-front",
                        "common_enemy": true,
                        "route_confirmed": true
                    }),
                ),
                options: vec![
                    DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    },
                    DecisionOption {
                        action: DecisionAction::Command {
                            command: serde_json::to_value(Command::OrderMovement {
                                subject: EntityRef::Army(ids.army),
                                destination: ids.eastern_territory,
                                cargo: Vec::new(),
                            })?,
                        },
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), -20),
                            ("alliance".to_owned(), 90),
                        ]),
                        ..DecisionOption::new("send-aid", "Send the neighboring army")
                    },
                ],
            },
        ),
    )?;
    canwu
        .step_canonical()?
        .expect("dynamic option refresh boundary");
    Ok(())
}

pub fn drive_decision( &mut self, due_at: SimTime, priority: i32, decision_request_id: DecisionRequestId, command_request_id: Option<CommandRequestId>, ticket_id: DecisionTicketId, policy: &dyn DecisionPolicy, ) -> Result<DecisionEvaluation, CanwuError>

Examples found in repository

examples/decision_ticket.rs (lines 159-166)

fn resolve_aid_request(canwu: &mut Canwu) -> Result<(), Box<dyn std::error::Error>> {
    let policy = WeightedUtilityPolicy::new(
        "aid-utility",
        "1",
        UtilityProfile {
            weights: BTreeMap::from([("alliance".to_owned(), 3), ("home_defense".to_owned(), 1)]),
        },
    );
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(4),
        Some(CommandRequestId::new(1)),
        DecisionTicketId::new(1),
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu
        .step_canonical()?
        .expect("decision resolution boundary");
    Ok(())
}

pub fn schedule_calendar_boundary( &mut self, due_at: SimTime, cadences: Vec<SystemCadence>, ) -> Result<IngressReceipt, CanwuError>

pub fn advance_canonical( &mut self, duration: SimDuration, ) -> Result<Vec<BoundaryReceipt>, CanwuError>

Examples found in repository

examples/continuous_game_loop.rs (line 233)

    fn render_frame(
        &mut self,
        wall_dt: Duration,
        speed: GameSpeed,
        phase_edge: bool,
    ) -> Result<(), CanwuError> {
        self.frame += 1;
        self.wall_elapsed += wall_dt;

        let converted_wall_nanos = wall_dt.as_nanos() * BASE_SIM_SECONDS_PER_WALL_SECOND;
        self.accumulated_sim_nanos += converted_wall_nanos * speed.multiplier();

        let mut authority_changed = false;
        while self.accumulated_sim_nanos >= SIMULATION_MINUTE_NANOS {
            let receipts = self.authority.advance_canonical(SIMULATION_QUANTUM)?;
            self.canonical_boundaries += receipts.len();
            authority_changed |= !receipts.is_empty();
            self.accumulated_sim_nanos -= SIMULATION_MINUTE_NANOS;
        }

        if authority_changed {
            self.refresh_presentation_from_authority();
        }

        let progress = self.presentation.render(self.presentation_time());
        let crossed_milestone = self.crossed_progress_milestone(progress);
        let has_new_events = self.reported_events < self.authority.events().len();

        if self.verbose && (phase_edge || crossed_milestone || has_new_events) {
            self.print_frame(speed);
        }
        self.report_new_events();
        Ok(())
    }

    /// This host never backdates mid-quantum input. It deterministically rounds
    /// up to the next representable Canwu minute; another host may choose a
    /// different policy, but it must apply the same policy across render FPS.
    fn submit_player_command(&mut self) -> Result<(), CanwuError> {
        let captured_at = self.presentation_time();
        let due_at = if self.accumulated_sim_nanos == 0 {
            self.authority.time()
        } else {
            self.authority
                .time()
                .checked_add(SIMULATION_QUANTUM)
                .expect("the scripted command time must remain representable")
        };
        let envelope = CommandEnvelope::new(
            Issuer::Actor(self.ids.commander),
            Command::OrderMovement {
                subject: EntityRef::Army(self.ids.army),
                destination: self.ids.eastern_territory,
                cargo: Vec::new(),
            },
        )
        .at_time(due_at);
        let request = CommandRequest::new(
            CommandRequestId::new(1),
            self.authority.revision(),
            envelope,
        );
        let ingress = self.authority.enqueue_command(due_at, 0, request)?;

        if self.verbose {
            println!(
                "INPUT: queued commander move as {:?}, captured_at={captured_at}, quantized_due_at={due_at}",
                ingress.ingress_id,
            );
        }

        // This drains ingress due at the current canonical time only. The
        // mid-quantum command remains queued until normal accumulation reaches
        // its quantized minute; future scheduled work is never jumped to.
        let receipts = self.authority.advance_canonical(SimDuration::ZERO)?;
        self.canonical_boundaries += receipts.len();
        self.refresh_presentation_from_authority();
        self.presentation.render(self.presentation_time());
        if self.verbose {
            self.print_frame(GameSpeed::X1);
        }
        self.report_new_events();
        Ok(())
    }

pub fn step_canonical(&mut self) -> Result<Option<BoundaryReceipt>, CanwuError>

Examples found in repository

examples/decision_ticket.rs (line 95)

fn open_aid_request(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    let now = canwu.time();
    let controller = DecisionControllerBinding::new(
        "warlord-b-ai",
        DecisionPolicyIdentity::new(DecisionPolicyKind::Utility, "aid-utility", "1"),
        DecisionAuthority::Actor {
            actor: ids.commander,
        },
    )
    .with_command_subject(EntityRef::Army(ids.army));

    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(1),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(2),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: DecisionTicketId::new(1),
                    definition: "beiyang.request-military-aid".to_owned(),
                    decision_maker: EntityRef::Person(ids.commander),
                    assigned_controller: "warlord-b-ai".to_owned(),
                    summary: "Neighboring warlord requests immediate military aid".to_owned(),
                    context: DecisionContext::new(
                        "beiyang.aid-request.v1",
                        json!({
                            "requester": "warlord-a",
                            "battle": "ongoing-front",
                            "common_enemy": true
                        }),
                    ),
                    options: vec![DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    }],
                    deadline: Some(now + SimDuration::days(2)),
                },
            },
        ),
    )?;
    canwu.step_canonical()?.expect("decision intake boundary");
    Ok(())
}

fn refresh_aid_options(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    canwu.enqueue_decision(
        canwu.time(),
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(3),
            canwu.revision(),
            DecisionMutation::ReplaceOptions {
                ticket_id: DecisionTicketId::new(1),
                expected_version: 1,
                context: DecisionContext::new(
                    "beiyang.aid-request.v1",
                    json!({
                        "requester": "warlord-a",
                        "battle": "ongoing-front",
                        "common_enemy": true,
                        "route_confirmed": true
                    }),
                ),
                options: vec![
                    DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    },
                    DecisionOption {
                        action: DecisionAction::Command {
                            command: serde_json::to_value(Command::OrderMovement {
                                subject: EntityRef::Army(ids.army),
                                destination: ids.eastern_territory,
                                cargo: Vec::new(),
                            })?,
                        },
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), -20),
                            ("alliance".to_owned(), 90),
                        ]),
                        ..DecisionOption::new("send-aid", "Send the neighboring army")
                    },
                ],
            },
        ),
    )?;
    canwu
        .step_canonical()?
        .expect("dynamic option refresh boundary");
    Ok(())
}

fn resolve_aid_request(canwu: &mut Canwu) -> Result<(), Box<dyn std::error::Error>> {
    let policy = WeightedUtilityPolicy::new(
        "aid-utility",
        "1",
        UtilityProfile {
            weights: BTreeMap::from([("alliance".to_owned(), 3), ("home_defense".to_owned(), 1)]),
        },
    );
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(4),
        Some(CommandRequestId::new(1)),
        DecisionTicketId::new(1),
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu
        .step_canonical()?
        .expect("decision resolution boundary");
    Ok(())
}

pub fn advance( &mut self, duration: SimDuration, ) -> Result<Vec<SimEvent>, CanwuError>

Examples found in repository

examples/move_army.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

pub fn settle_boundary( &mut self, request: BoundaryRequest, ) -> Result<BoundaryReceipt, CanwuError>

Examples found in repository

examples/phased_boundary.rs (line 155)

fn main() -> Result<(), CanwuError> {
    let mut canwu = Canwu::demo(35)?;
    canwu.register_plugin(&SupplyPlugin)?;
    canwu.register_plugin(&DemandPlugin)?;

    let receipt = canwu
        .settle_boundary(BoundaryRequest::at(canwu.time()).with_cadence(SystemCadence::Daily))?;
    assert_eq!(receipt.allocations[0].granted, 6);
    assert_eq!(canwu.boundaries()[0].emissions.len(), 2);
    Ok(())
}

pub fn wait( &mut self, duration: SimDuration, ) -> Result<Vec<SimEvent>, CanwuError>

pub fn step(&mut self) -> Result<Vec<SimEvent>, CanwuError>

pub fn snapshot(&self) -> SimulationSnapshot

Examples found in repository

examples/decision_ticket.rs (line 32)

fn replay_scenario(canwu: &Canwu) -> Scenario {
    let initial = canwu.snapshot();
    Scenario {
        start_time: initial.initial_time,
        world: initial.world,
        knowledge: initial.knowledge,
        domain_records: Vec::new(),
    }
}

fn open_aid_request(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    let now = canwu.time();
    let controller = DecisionControllerBinding::new(
        "warlord-b-ai",
        DecisionPolicyIdentity::new(DecisionPolicyKind::Utility, "aid-utility", "1"),
        DecisionAuthority::Actor {
            actor: ids.commander,
        },
    )
    .with_command_subject(EntityRef::Army(ids.army));

    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(1),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(2),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: DecisionTicketId::new(1),
                    definition: "beiyang.request-military-aid".to_owned(),
                    decision_maker: EntityRef::Person(ids.commander),
                    assigned_controller: "warlord-b-ai".to_owned(),
                    summary: "Neighboring warlord requests immediate military aid".to_owned(),
                    context: DecisionContext::new(
                        "beiyang.aid-request.v1",
                        json!({
                            "requester": "warlord-a",
                            "battle": "ongoing-front",
                            "common_enemy": true
                        }),
                    ),
                    options: vec![DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    }],
                    deadline: Some(now + SimDuration::days(2)),
                },
            },
        ),
    )?;
    canwu.step_canonical()?.expect("decision intake boundary");
    Ok(())
}

fn refresh_aid_options(canwu: &mut Canwu, ids: DemoIds) -> Result<(), Box<dyn std::error::Error>> {
    canwu.enqueue_decision(
        canwu.time(),
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(3),
            canwu.revision(),
            DecisionMutation::ReplaceOptions {
                ticket_id: DecisionTicketId::new(1),
                expected_version: 1,
                context: DecisionContext::new(
                    "beiyang.aid-request.v1",
                    json!({
                        "requester": "warlord-a",
                        "battle": "ongoing-front",
                        "common_enemy": true,
                        "route_confirmed": true
                    }),
                ),
                options: vec![
                    DecisionOption {
                        action: DecisionAction::None,
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), 80),
                            ("alliance".to_owned(), -40),
                        ]),
                        ..DecisionOption::new("decline", "Decline aid")
                    },
                    DecisionOption {
                        action: DecisionAction::Command {
                            command: serde_json::to_value(Command::OrderMovement {
                                subject: EntityRef::Army(ids.army),
                                destination: ids.eastern_territory,
                                cargo: Vec::new(),
                            })?,
                        },
                        utility_inputs: BTreeMap::from([
                            ("home_defense".to_owned(), -20),
                            ("alliance".to_owned(), 90),
                        ]),
                        ..DecisionOption::new("send-aid", "Send the neighboring army")
                    },
                ],
            },
        ),
    )?;
    canwu
        .step_canonical()?
        .expect("dynamic option refresh boundary");
    Ok(())
}

fn resolve_aid_request(canwu: &mut Canwu) -> Result<(), Box<dyn std::error::Error>> {
    let policy = WeightedUtilityPolicy::new(
        "aid-utility",
        "1",
        UtilityProfile {
            weights: BTreeMap::from([("alliance".to_owned(), 3), ("home_defense".to_owned(), 1)]),
        },
    );
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(4),
        Some(CommandRequestId::new(1)),
        DecisionTicketId::new(1),
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu
        .step_canonical()?
        .expect("decision resolution boundary");
    Ok(())
}

fn verify_persistence_and_replay(
    canwu: &Canwu,
    replay_scenario: Scenario,
) -> Result<(), Box<dyn std::error::Error>> {
    let snapshot = canwu.snapshot();
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), snapshot);
    let replayed = Canwu::replay_from_journal(replay_scenario, &[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), snapshot);
    Ok(())
}

pub fn snapshot_json(&self) -> Result<String, CanwuError>

pub fn from_snapshot_json(json: &str) -> Result<Self, CanwuError>

Examples found in repository

examples/decision_ticket.rs (line 179)

fn verify_persistence_and_replay(
    canwu: &Canwu,
    replay_scenario: Scenario,
) -> Result<(), Box<dyn std::error::Error>> {
    let snapshot = canwu.snapshot();
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), snapshot);
    let replayed = Canwu::replay_from_journal(replay_scenario, &[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), snapshot);
    Ok(())
}

pub fn from_snapshot_json_with_plugins( json: &str, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn from_checkpoint_and_journal( checkpoint: SimulationCheckpoint, segments: Vec<EvidenceJournalSegment>, ) -> Result<Self, CanwuError>

pub fn from_checkpoint_journal( bundle: CheckpointJournal, ) -> Result<Self, CanwuError>

pub fn from_checkpoint_journal_with_plugins( bundle: CheckpointJournal, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn from_checkpoint_journal_json(json: &str) -> Result<Self, CanwuError>

pub fn from_checkpoint_journal_json_with_plugins( json: &str, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

pub fn replay( seed: u64, scenario: Scenario, commands: &[CommandRecord], final_time: SimTime, ) -> Result<Self, CanwuError>

pub fn replay_with_plugins( seed: u64, scenario: Scenario, plugins: &[&dyn SimulationPlugin], commands: &[CommandRecord], final_time: SimTime, ) -> Result<Self, CanwuError>

pub fn replay_with_boundaries( seed: u64, scenario: Scenario, plugins: &[&dyn SimulationPlugin], commands: &[CommandRecord], boundaries: &[BoundaryRecord], final_time: SimTime, ) -> Result<Self, CanwuError>

pub fn replay_with_run_manifest( seed: u64, scenario: Scenario, run_manifest: RunManifest, plugins: &[&dyn SimulationPlugin], commands: &[CommandRecord], boundaries: &[BoundaryRecord], final_time: SimTime, ) -> Result<Self, CanwuError>

pub fn replay_with_run_configuration( seed: u64, scenario: Scenario, run_manifest: RunManifest, run_configuration: RunConfiguration, plugins: &[&dyn SimulationPlugin], commands: &[CommandRecord], command_attempts: &[CommandAttemptRecord], boundaries: &[BoundaryRecord], final_time: SimTime, ) -> Result<Self, CanwuError>

pub fn replay_from_journal( scenario: Scenario, plugins: &[&dyn SimulationPlugin], journal: &ReplayJournal, ) -> Result<Self, CanwuError>

Examples found in repository

examples/decision_ticket.rs (line 181)

fn verify_persistence_and_replay(
    canwu: &Canwu,
    replay_scenario: Scenario,
) -> Result<(), Box<dyn std::error::Error>> {
    let snapshot = canwu.snapshot();
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), snapshot);
    let replayed = Canwu::replay_from_journal(replay_scenario, &[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), snapshot);
    Ok(())
}

pub fn fork(&self) -> Self

pub fn diff(&self, other: &Self) -> WorldDiff

pub fn query(&self, query: &Query) -> QueryResult

pub fn query_as( &self, actor: PersonId, query: &Query, ) -> Result<QueryResult, CanwuError>

pub fn admin_query_knowledge( &self, holder: KnowledgeHolderRef, query: &KnowledgeQuery, ) -> Result<KnowledgeQueryResult, CanwuError>

Trusted host/admin holder query. Player-facing callers must use a restricted CanwuViewer.

pub fn viewer(&self) -> Result<CanwuViewer<'_>, CanwuError>

Creates the restricted viewer dictated entirely by the persisted run policy and seat binding.

pub fn viewer_for_actor( &self, actor: PersonId, ) -> Result<CanwuViewer<'_>, CanwuError>

Character-seat and compatibility convenience. It never upgrades an institution, public, research, or developer policy to a person.

pub fn viewer_context( &self, actor: PersonId, ) -> Result<ViewerContext, CanwuError>

Builds an authorized viewer context from the persisted run policy.

Callers cannot select a stronger observation policy through an observation request; the run configuration is the input-control boundary for actor-relative versus research projections.

pub fn observe( &self, actor: PersonId, request: &ObserveRequest, ) -> Result<AgentContext, CanwuError>

Examples found in repository

examples/move_army.rs (line 17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

pub fn observe_with_viewer( &self, viewer: &ViewerContext, request: &ObserveRequest, ) -> Result<AgentContext, CanwuError>

Projects the simulation for a previously authorized viewer context.

The context controls only the player-facing projection. Plugin system subscriptions and state read permissions remain enforced by the simulation runtime and are not widened by this method.

pub fn inspect( &self, actor: PersonId, entity: &EntityRef, detail: DetailLevel, ) -> Result<Inspection, CanwuError>

pub fn available_actions( &self, actor: PersonId, ) -> Result<Vec<AvailableAction>, CanwuError>

pub fn act( &mut self, actor: PersonId, action: SemanticAction, ) -> Result<CommandReceipt, CanwuError>

Examples found in repository

examples/move_army.rs (lines 7-14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(35)?;
    let ids = Canwu::demo_ids();

    canwu.act(
        ids.commander,
        SemanticAction::MoveEntity {
            subject: EntityRef::Army(ids.army),
            destination: ids.eastern_territory,
            cargo: Vec::new(),
        },
    )?;
    let arrival_events = canwu.advance(SimDuration::days(1))?;

    let commander = canwu.observe(ids.commander, &ObserveRequest::default())?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!("time: {}", canwu.time());
    println!("arrival events: {}", arrival_events.len());
    println!(
        "commander knows location: {:?}",
        commander.known_armies[0].known_location
    );
    println!(
        "observer still believes location: {:?}",
        observer.known_armies[0].known_location
    );

    canwu.advance(SimDuration::days(3))?;
    let observer = canwu.observe(ids.observer, &ObserveRequest::default())?;
    println!(
        "observer after report: {:?}",
        observer.known_armies[0].known_location
    );
    Ok(())
}

pub fn explain(&self, request: &ExplanationRequest) -> Explanation

pub fn describe_capabilities(&self) -> CapabilityDescription