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>

Examples found in repository

examples/governance_transition.rs (line 555)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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>

Deprecated compatibility scenario. New hosts should use an integration-owned scenario.

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/decision_ticket.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    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_trace(canwu_api::DecisionTraceId::new(1))
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

    verify_persistence_and_replay(&canwu)?;
    println!("snapshot_restore=ok exact_replay=ok");
    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/uncertainty_resolution.rs (line 149)

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    Ok(())
}

pub fn demo_ids() -> DemoIds

IDs for the deprecated compatibility scenario.

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/decision_ticket.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    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_trace(canwu_api::DecisionTraceId::new(1))
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

    verify_persistence_and_replay(&canwu)?;
    println!("snapshot_restore=ok exact_replay=ok");
    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/uncertainty_resolution.rs (line 123)

fn enqueue_ticket(
    canwu: &mut Canwu,
    ticket_id: DecisionTicketId,
    request_offset: u64,
    controller: DecisionControllerBinding,
) -> Result<(), CanwuError> {
    let now = canwu.time();
    let controller_id = controller.id.clone();
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset + 1),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: ticket_id,
                    definition: "example.law-passage".to_owned(),
                    decision_maker: EntityRef::Person(Canwu::demo_ids().commander),
                    assigned_controller: controller_id,
                    summary: "Will the proposed law pass?".to_owned(),
                    context: DecisionContext::new(
                        "example.law-passage.v1",
                        json!({
                            "supporting_seats": 72,
                            "opposing_seats": 28,
                            "public_pressure": "high"
                        }),
                    ),
                    options: vec![
                        DecisionOption::new("pass", "Pass the law"),
                        DecisionOption::new("fail", "Reject the law"),
                    ],
                    deadline: None,
                    parent_ticket: None,
                },
            },
        ),
    )?;
    canwu.settle_boundary(canwu_api::BoundaryRequest::at(now))?;
    Ok(())
}

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    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/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/uncertainty_resolution.rs (line 102)

fn enqueue_ticket(
    canwu: &mut Canwu,
    ticket_id: DecisionTicketId,
    request_offset: u64,
    controller: DecisionControllerBinding,
) -> Result<(), CanwuError> {
    let now = canwu.time();
    let controller_id = controller.id.clone();
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset + 1),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: ticket_id,
                    definition: "example.law-passage".to_owned(),
                    decision_maker: EntityRef::Person(Canwu::demo_ids().commander),
                    assigned_controller: controller_id,
                    summary: "Will the proposed law pass?".to_owned(),
                    context: DecisionContext::new(
                        "example.law-passage.v1",
                        json!({
                            "supporting_seats": 72,
                            "opposing_seats": 28,
                            "public_pressure": "high"
                        }),
                    ),
                    options: vec![
                        DecisionOption::new("pass", "Pass the law"),
                        DecisionOption::new("fail", "Reject the law"),
                    ],
                    deadline: None,
                    parent_ticket: None,
                },
            },
        ),
    )?;
    canwu.settle_boundary(canwu_api::BoundaryRequest::at(now))?;
    Ok(())
}

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    Ok(())
}

examples/decision_ticket.rs (line 30)

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)),
                    parent_ticket: None,
                },
            },
        ),
    )?;
    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/uncertainty_resolution.rs (line 109)

fn enqueue_ticket(
    canwu: &mut Canwu,
    ticket_id: DecisionTicketId,
    request_offset: u64,
    controller: DecisionControllerBinding,
) -> Result<(), CanwuError> {
    let now = canwu.time();
    let controller_id = controller.id.clone();
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset + 1),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: ticket_id,
                    definition: "example.law-passage".to_owned(),
                    decision_maker: EntityRef::Person(Canwu::demo_ids().commander),
                    assigned_controller: controller_id,
                    summary: "Will the proposed law pass?".to_owned(),
                    context: DecisionContext::new(
                        "example.law-passage.v1",
                        json!({
                            "supporting_seats": 72,
                            "opposing_seats": 28,
                            "public_pressure": "high"
                        }),
                    ),
                    options: vec![
                        DecisionOption::new("pass", "Pass the law"),
                        DecisionOption::new("fail", "Reject the law"),
                    ],
                    deadline: None,
                    parent_ticket: None,
                },
            },
        ),
    )?;
    canwu.settle_boundary(canwu_api::BoundaryRequest::at(now))?;
    Ok(())
}

examples/decision_ticket.rs (line 45)

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)),
                    parent_ticket: None,
                },
            },
        ),
    )?;
    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 entities(&self) -> impl Iterator<Item = &EntityRef>

pub fn entity_exists(&self, entity: &EntityRef) -> bool

pub fn world(&self) -> WorldSnapshot

Deprecated detached format-5 compatibility projection.

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 person_availability( &self, person: PersonId, ) -> Option<&PersonAvailability>

Trusted host access to a person’s committed life and custody state. None means no change has been committed: the person is alive and free.

pub fn person_availabilities( &self, ) -> impl Iterator<Item = (&PersonId, &PersonAvailability)>

Trusted host access to every committed person availability, in person-ID order. Persons without an entry are alive and free.

pub fn pending_transition_manifests( &self, ) -> impl Iterator<Item = &PendingTransitionManifest>

Trusted host access to the registered transition manifests whose ready boundary has not settled, in manifest-ID order. Settled manifests leave their audit on the boundary record and receipt.

pub fn knowledge(&self) -> &KnowledgeSnapshot

Trusted host/admin access to the complete knowledge snapshot.

Do not expose this public API 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 domain_record_version_evidence_exists( &self, reference: &DomainRecordVersionRef, ) -> bool

Returns whether an exact domain-record version exists in current or retained evidence.

pub fn evidence_exists(&self, reference: &EvidenceRef) -> bool

Returns whether a generic evidence identity is retained or archived.

pub fn evidence_time(&self, reference: &EvidenceRef) -> Option<SimTime>

Returns when retained evidence first became authoritative.

Compacted identity-only receipts return None; load the archived evidence body before making decisions that require temporal ordering.

pub fn domain_record_version( &self, reference: &DomainRecordVersionRef, ) -> Option<DomainRecord>

Resolves the retained record body for one exact domain-record version.

A compacted archive receipt proves existence but does not expose the version body through this trusted-host query.

pub fn current_domain_record_version( &self, reference: &DomainRecordRef, ) -> Result<Option<DomainRecordVersionRef>, CanwuError>

Returns the retained or archive-resolvable exact identity for the authoritative current record version. Missing provenance fails closed.

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

Examples found in repository

examples/governance_transition.rs (line 566)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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

pub fn domain_record_page( &self, kind: &DomainRecordKind, after: Option<&DomainRecordRef>, limit: usize, expected_revision: Option<u64>, ) -> Result<DomainRecordPage, CanwuError>

Returns one trusted-host page bound to an authoritative revision.

Use the returned revision as expected_revision on subsequent pages.

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

Examples found in repository

examples/uncertainty_resolution.rs (line 200)

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    Ok(())
}

pub fn decision_controller( &self, id: &str, ) -> Option<&DecisionControllerBinding>

pub fn decision_trace(&self, id: DecisionTraceId) -> Option<&DecisionTrace>

Examples found in repository

examples/decision_ticket.rs (line 20)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(1918)?;
    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_trace(canwu_api::DecisionTraceId::new(1))
        .expect("utility decision trace");
    println!("{}", serde_json::to_string_pretty(trace)?);

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

examples/uncertainty_resolution.rs (line 170)

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

pub fn decision_attempt( &self, id: DecisionRequestId, ) -> Option<&DecisionAttemptRecord>

pub fn decision_hot_state(&self) -> DecisionHotState

pub fn decision_history_location( &self, key: &DecisionHistoryKey, ) -> DecisionHistoryLocation

pub fn decision_history_location_with_provider( &self, key: &DecisionHistoryKey, provider: &dyn DecisionArchiveProvider, ) -> Result<DecisionHistoryLocation, CanwuError>

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_journal_replay(
    canwu: &Canwu,
    snapshot: &canwu_api::SimulationSnapshot,
) -> Result<(), Box<dyn std::error::Error>> {
    let replayed = Canwu::replay_from_journal(&[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), *snapshot);
    Ok(())
}

examples/governance_transition.rs (line 577)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

pub fn outbox_entries(&self) -> Result<Vec<OutboxEntry>, CanwuError>

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

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

pub fn archive_reachability_manifest( &self, retained_checkpoints: &[SimulationCheckpoint], page_retention: &StatePageRetentionLedger, decision_provider: &dyn DecisionArchiveProvider, plugin_provider: &dyn PluginArchiveObjectProvider, ) -> Result<ArchiveReachabilityManifest, 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(())
}

examples/uncertainty_resolution.rs (line 150)

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

pub fn set_plugin_archive_object_provider( &mut self, provider: Rc<dyn PluginArchiveObjectProvider>, )

Attaches caller-owned package archive storage for authenticated cold history resolution during normal admissions, settlement, and queries.

pub fn plugin_archive_object( &self, namespace: &str, object_id: &str, ) -> Result<Option<Vec<u8>>, CanwuError>

Loads one opaque package archive object from the attached provider. Package integrations authenticate the bytes against their committed archive roots before use.

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>

Examples found in repository

examples/governance_transition.rs (lines 557-562)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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

pub fn cancel_plugin_ingress( &mut self, ingress_id: IngressId, reason: impl Into<String>, ) -> Result<IngressReceipt, CanwuError>

Withdraws a still-pending plugin ingress item that the host enqueued with Self::enqueue_plugin_ingress, strictly before its due time.

Due, admitted, archived, or already cancelled items fail with ErrorCode::LateIngress; items of internal packet types or items a plugin scheduled inside the engine fail with ErrorCode::InvalidAuthority; unknown IDs fail with ErrorCode::EvidenceUnavailable; non-plugin targets and reasons that are empty, untrimmed, or longer than MAX_INGRESS_CANCELLATION_REASON_BYTES fail with ErrorCode::InvalidPayload; declared read-only runs fail with ErrorCode::InteractionReadOnly. The returned receipt names the terminal IngressPayload::PluginCancellation journal record. The withdrawn item is never admitted, never settles, and nothing is rolled back; snapshots, checkpoint journals, and exact replay preserve the cancellation.

pub fn cancel_permitted_plugin_ingress( &mut self, ingress_id: IngressId, permit: &PluginIngressPermit, reason: impl Into<String>, ) -> Result<IngressReceipt, CanwuError>

Withdraws a still-pending item of an internal packet type through the owning plugin’s opaque registration permit. The permit covers host-enqueued items of that exact type and items the same plugin scheduled inside the engine; timing rules match Self::cancel_plugin_ingress.

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/uncertainty_resolution.rs (lines 104-112)

fn enqueue_ticket(
    canwu: &mut Canwu,
    ticket_id: DecisionTicketId,
    request_offset: u64,
    controller: DecisionControllerBinding,
) -> Result<(), CanwuError> {
    let now = canwu.time();
    let controller_id = controller.id.clone();
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset + 1),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: ticket_id,
                    definition: "example.law-passage".to_owned(),
                    decision_maker: EntityRef::Person(Canwu::demo_ids().commander),
                    assigned_controller: controller_id,
                    summary: "Will the proposed law pass?".to_owned(),
                    context: DecisionContext::new(
                        "example.law-passage.v1",
                        json!({
                            "supporting_seats": 72,
                            "opposing_seats": 28,
                            "public_pressure": "high"
                        }),
                    ),
                    options: vec![
                        DecisionOption::new("pass", "Pass the law"),
                        DecisionOption::new("fail", "Reject the law"),
                    ],
                    deadline: None,
                    parent_ticket: None,
                },
            },
        ),
    )?;
    canwu.settle_boundary(canwu_api::BoundaryRequest::at(now))?;
    Ok(())
}

examples/decision_ticket.rs (lines 40-48)

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)),
                    parent_ticket: None,
                },
            },
        ),
    )?;
    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 148-155)

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(())
}

examples/uncertainty_resolution.rs (lines 217-224)

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    Ok(())
}

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

Examples found in repository

examples/uncertainty_resolution.rs (line 164)

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

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/uncertainty_resolution.rs (line 165)

fn random_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    canwu.register_plugin(&UncertaintyPlugin)?;
    enqueue_ticket(
        &mut canwu,
        RANDOM_TICKET,
        1,
        DecisionControllerBinding::new(
            "law-random-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Random, "weighted-random", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let selection_at = SimTime::EPOCH + SimDuration::days(1);
    canwu.schedule_calendar_boundary(selection_at, vec![SystemCadence::Daily])?;
    canwu.step_canonical()?.expect("random source boundary");
    canwu
        .step_canonical()?
        .expect("generated decision resolution boundary");
    let trace = canwu
        .decision_trace(canwu_api::DecisionTraceId::new(1))
        .expect("random decision trace");
    println!("random_trace={}", serde_json::to_string(trace)?);
    Ok(())
}

fn llm_interface_branch() -> Result<(), Box<dyn std::error::Error>> {
    let mut canwu = Canwu::demo(202)?;
    let ticket_id = DecisionTicketId::new(2);
    enqueue_ticket(
        &mut canwu,
        ticket_id,
        10,
        DecisionControllerBinding::new(
            "law-llm-controller",
            DecisionPolicyIdentity::new(DecisionPolicyKind::Llm, "strict-law-selector", "1"),
            DecisionAuthority::Actor {
                actor: Canwu::demo_ids().commander,
            },
        ),
    )?;
    let mut policy = QueuedLlmPolicy::new(
        "strict-law-selector",
        "1",
        LlmModelIdentity {
            provider: "not-connected".to_owned(),
            model: "host-selected-model".to_owned(),
            prompt_contract: "return one existing option_id and no new action".to_owned(),
        },
    );
    let ticket = canwu.decision_ticket(ticket_id).expect("LLM ticket");
    let request = policy.external_request(ticket);
    println!("llm_request={}", serde_json::to_string(&request)?);

    // A real host sends `request` to its model and parses a strict structured
    // answer. This example supplies the same response object without making a
    // network call.
    policy.submit(
        ticket_id,
        ExternalDecisionResponse {
            ticket_version: request.ticket_version,
            option_id: "pass".to_owned(),
            provider: "not-connected".to_owned(),
            request_id: "example-response-1".to_owned(),
            metadata: BTreeMap::new(),
        },
    )?;
    let evaluation = canwu.drive_decision(
        canwu.time(),
        0,
        DecisionRequestId::new(12),
        None,
        ticket_id,
        &policy,
    )?;
    assert!(matches!(evaluation, DecisionEvaluation::Prepared(_)));
    canwu.step_canonical()?.expect("LLM decision boundary");
    Ok(())
}

examples/decision_ticket.rs (line 84)

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)),
                    parent_ticket: None,
                },
            },
        ),
    )?;
    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>

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(())
}

examples/governance_transition.rs (line 564)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

examples/uncertainty_resolution.rs (line 144)

fn enqueue_ticket(
    canwu: &mut Canwu,
    ticket_id: DecisionTicketId,
    request_offset: u64,
    controller: DecisionControllerBinding,
) -> Result<(), CanwuError> {
    let now = canwu.time();
    let controller_id = controller.id.clone();
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset),
            canwu.revision(),
            DecisionMutation::RegisterController { controller },
        ),
    )?;
    canwu.enqueue_decision(
        now,
        0,
        DecisionIngressRequest::new(
            DecisionRequestId::new(request_offset + 1),
            canwu.revision(),
            DecisionMutation::Open {
                ticket: DecisionTicketDraft {
                    id: ticket_id,
                    definition: "example.law-passage".to_owned(),
                    decision_maker: EntityRef::Person(Canwu::demo_ids().commander),
                    assigned_controller: controller_id,
                    summary: "Will the proposed law pass?".to_owned(),
                    context: DecisionContext::new(
                        "example.law-passage.v1",
                        json!({
                            "supporting_seats": 72,
                            "opposing_seats": 28,
                            "public_pressure": "high"
                        }),
                    ),
                    options: vec![
                        DecisionOption::new("pass", "Pass the law"),
                        DecisionOption::new("fail", "Reject the law"),
                    ],
                    deadline: None,
                    parent_ticket: None,
                },
            },
        ),
    )?;
    canwu.settle_boundary(canwu_api::BoundaryRequest::at(now))?;
    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 164)

fn verify_persistence_and_replay(canwu: &Canwu) -> Result<(), Box<dyn std::error::Error>> {
    let snapshot = canwu.snapshot();
    verify_snapshot_round_trip(&snapshot)?;
    verify_journal_replay(canwu, &snapshot)
}

fn verify_snapshot_round_trip(
    snapshot: &canwu_api::SimulationSnapshot,
) -> Result<(), Box<dyn std::error::Error>> {
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), *snapshot);
    Ok(())
}

fn verify_journal_replay(
    canwu: &Canwu,
    snapshot: &canwu_api::SimulationSnapshot,
) -> Result<(), Box<dyn std::error::Error>> {
    let replayed = Canwu::replay_from_journal(&[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), *snapshot);
    Ok(())
}

examples/governance_transition.rs (line 578)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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

Examples found in repository

examples/governance_transition.rs (line 575)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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

Examples found in repository

examples/decision_ticket.rs (line 172)

fn verify_snapshot_round_trip(
    snapshot: &canwu_api::SimulationSnapshot,
) -> Result<(), Box<dyn std::error::Error>> {
    let restored = Canwu::from_snapshot_json(&serde_json::to_string(&snapshot)?)?;
    assert_eq!(restored.snapshot(), *snapshot);
    Ok(())
}

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

Examples found in repository

examples/governance_transition.rs (line 576)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

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_from_journal( plugins: &[&dyn SimulationPlugin], journal: &ReplayJournal, ) -> Result<Self, CanwuError>

Examples found in repository

examples/decision_ticket.rs (line 181)

fn verify_journal_replay(
    canwu: &Canwu,
    snapshot: &canwu_api::SimulationSnapshot,
) -> Result<(), Box<dyn std::error::Error>> {
    let replayed = Canwu::replay_from_journal(&[], &canwu.replay_journal())?;
    assert_eq!(replayed.snapshot(), *snapshot);
    Ok(())
}

examples/governance_transition.rs (line 577)

fn main() -> Result<(), CanwuError> {
    let central = CentralPlugin;
    let treasury = TreasuryPlugin;
    let county = CountyPlugin;
    let plugins: [&dyn SimulationPlugin; 3] = [&central, &treasury, &county];
    let mut canwu =
        Canwu::new_with_plugins(11, Scenario::new(SimTime::EPOCH, Vec::new()), &plugins)?;

    canwu.enqueue_plugin_ingress(canwu_api::PluginIngressRequest::new(
        CENTRAL_PLUGIN,
        ISSUE_INGRESS,
        SimTime::EPOCH,
        json!({"order_id": ORDER_ID}),
    ))?;

    let first = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(first.generated_ingress.len(), 2);
    assert!(canwu.typed_domain_record(&order_reference()).is_some());
    assert!(canwu.typed_domain_record(&treasury_reference()).is_none());
    assert!(canwu.typed_domain_record(&county_reference()).is_none());

    let second = canwu.settle_boundary(BoundaryRequest::at(SimTime::EPOCH))?;
    assert_eq!(second.record_change_count, 2);
    assert!(canwu.typed_domain_record(&treasury_reference()).is_some());
    assert!(canwu.typed_domain_record(&county_reference()).is_some());

    let snapshot = canwu.snapshot_json()?;
    let restored = Canwu::from_snapshot_json_with_plugins(&snapshot, &plugins)?;
    let replayed = Canwu::replay_from_journal(&plugins, &canwu.replay_journal())?;
    assert_eq!(restored.snapshot(), canwu.snapshot());
    assert_eq!(replayed.snapshot(), canwu.snapshot());

    println!(
        "relief_order={} treasury_grain={} county_grain={} exact_replay=ok",
        ORDER_ID, 600, 600
    );
    Ok(())
}

pub fn replay_from_journal_with_archive_provider( plugins: &[&dyn SimulationPlugin], journal: &ReplayJournal, archive_provider: Rc<dyn PluginArchiveObjectProvider>, ) -> Result<Self, CanwuError>

Replays with package archive storage attached before the first recorded boundary, so package-owned cold history participates in ordinary admission and settlement throughout replay.

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

pub fn fork(&self) -> Self

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>

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

Trait Implementations

impl PluginArchiveObjectProvider for Canwu

fn load_plugin_archive_object( &self, namespace: &str, object_id: &str, ) -> Result<Option<Vec<u8>>, CanwuError>