Struct SimulationView 

pub struct SimulationView<'a> { /* private fields */ }

Implementations

impl SimulationView<'_>

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

Loads a package-owned cold object through the host provider attached to this runtime. Package code remains responsible for authenticating the bytes against its committed archive root before using them.

pub const fn time(&self) -> SimTime

pub fn army(&self, id: ArmyId) -> Result<Option<&Army>, CanwuError>

Examples found in repository

examples/plugin.rs (line 22)

fn set_stance(
    view: &SimulationView<'_>,
    context: &CommandContext,
    payload: &Value,
) -> Result<Vec<SystemDirective>, CanwuError> {
    let army = ArmyId::new(
        payload
            .get("army")
            .and_then(Value::as_u64)
            .expect("payload was validated before the handler ran"),
    );
    let Some(army_state) = view.army(army)? else {
        return Err(CanwuError::new(
            ErrorCode::ArmyNotFound,
            format!("army {army} was not found"),
        ));
    };
    if context.issuer != Issuer::Actor(army_state.commander) {
        return Err(CanwuError::new(
            ErrorCode::InvalidAuthority,
            "only the army commander may set its stance",
        ));
    }
    Ok(vec![SystemDirective::SetComponent {
        state: StateKey::new("military", "stance"),
        entity: EntityRef::Army(army),
        component: "stance".to_owned(),
        value: payload["stance"].clone(),
        summary: format!("Army {army} changed stance"),
    }])
}

pub fn person(&self, id: PersonId) -> Result<Option<&Person>, CanwuError>

pub fn person_availability( &self, id: PersonId, ) -> Result<Option<&PersonAvailability>, CanwuError>

Returns committed core availability for a person after an explicit canwu.core.person_availability read. None means alive and free.

pub fn persons_created_by_correlation( &self, plugin: &str, correlation: &str, ) -> Result<Vec<CreatedPerson>, CanwuError>

Finds committed person creations produced by one plugin with an exact correlation, so the proposing system can bind engine-allocated IDs at a later boundary. The lookup reads the persisted created-person registry, so it does not depend on retained evidence.

pub fn government( &self, id: GovernmentId, ) -> Result<Option<&Government>, CanwuError>

pub fn territory( &self, id: TerritoryId, ) -> Result<Option<&Territory>, CanwuError>

pub fn route(&self, id: RouteId) -> Result<Option<&Route>, CanwuError>

pub fn actor_knowledge( &self, actor: PersonId, ) -> Result<Option<&ActorKnowledge>, CanwuError>

pub fn knowledge_record_count_in_namespace( &self, namespace: &str, ) -> Result<usize, CanwuError>

Counts records in a knowledge namespace at the current proposal-visible cut.

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

Queries holder-relative records for an omniscient plugin system.

This enforces the declared canwu.core.knowledge read and returns an owned projection. It is not an actor-facing authorization API.

pub fn command( &self, id: CommandId, ) -> Result<Option<&CommandRecord>, CanwuError>

Resolves an exact command ID from the retained runtime journal in O(1).

An archived command remains valid identity evidence, but its payload is no longer available through this view: lookup returns ErrorCode::EvidenceContentUnavailable. None means the ID has neither retained content nor a committed archive receipt.

pub fn event(&self, id: EventId) -> Result<Option<&SimEvent>, CanwuError>

Resolves an exact event ID from the retained runtime journal in O(1).

An archived event remains valid identity evidence, but its payload is no longer available through this view: lookup returns ErrorCode::EvidenceContentUnavailable. None means the ID has neither retained content nor a committed archive receipt.

pub fn ingress( &self, id: IngressId, ) -> Result<Option<&IngressRecord>, CanwuError>

Examples found in repository

examples/governance_transition.rs (line 175)

fn owned_order_ingress(
    view: &SimulationView<'_>,
    context: &BoundaryContext,
    owner: &str,
    packet_type: &str,
) -> Result<Option<String>, CanwuError> {
    let mut order_id = None;
    for ingress_id in &context.admitted_ingress {
        let Some(record) = view.ingress(*ingress_id)? else {
            continue;
        };
        let IngressPayload::Plugin {
            plugin,
            packet_type: admitted_packet_type,
            payload,
            ..
        } = &record.payload
        else {
            continue;
        };
        if plugin != owner || admitted_packet_type != packet_type {
            continue;
        }
        if order_id.is_some() {
            return Err(CanwuError::new(
                ErrorCode::InvalidBoundary,
                format!("{owner} received duplicate {packet_type} ingress"),
            ));
        }
        let value = payload
            .get("order_id")
            .and_then(Value::as_str)
            .ok_or_else(|| {
                CanwuError::new(
                    ErrorCode::InvalidPayload,
                    format!("{owner}.{packet_type} is missing order_id"),
                )
            })?;
        order_id = Some(value.to_owned());
    }
    Ok(order_id)
}

pub fn cancellable_plugin_ingress( &self, ) -> Result<Vec<&IngressRecord>, CanwuError>

Lists the still-pending plugin ingress that this boundary system’s own plugin scheduled inside the engine and may withdraw with crate::BoundaryDirective::CancelPluginIngress, in ingress-ID order.

Only items due strictly after the view time are listed. Items that a boundary directive scheduled earlier in the current boundary appear from the next boundary; items generated by this plugin’s commands are listed as soon as they are queued. Views that are not bound to a boundary system list nothing.

pub fn transition_manifests( &self, ) -> Result<Vec<&PendingTransitionManifest>, CanwuError>

Lists the pending transition manifests that this boundary system’s plugin coordinates or participates in, in manifest-ID order, after an explicit canwu.core.transitions read.

A manifest’s expected versions name other plugins’ records, so the list is relative to the reading plugin; other plugins’ manifests and views not bound to a boundary system list nothing. Inside a boundary, a manifest registered by an earlier phase is listed from the next phase on, and a manifest that settled at phase 11 is no longer listed. A participant stages for the manifests whose ready_at is the current boundary and that list its plugin.

pub fn transition_audits( &self, ) -> Result<Vec<&TransitionAuditRecord>, CanwuError>

Returns the audits of the transition manifests that settled at phase 11 of the current boundary and that this boundary system’s plugin coordinates or participates in, in manifest-ID order, after an explicit canwu.core.transitions read.

A failed audit fails the boundary instead of leaving a record, so every outcome is crate::TransitionAuditOutcome::Committed or crate::TransitionAuditOutcome::Expired. Earlier phases and views not bound to a boundary system see no audits; hosts read settled audits from crate::BoundaryRecord::transition_audits and crate::BoundaryReceipt::transition_audits.

pub fn plugin_ingress_matches( &self, id: IngressId, plugin: &str, packet_type: &str, ) -> Result<bool, CanwuError>

Matches retained, plugin-generated ingress provenance without exposing its payload.

Durable evidence may cite ingress admitted at an earlier boundary, but a generated record still waiting in the scheduler is not yet admissible. Format-7 archive receipts retain a Merkle-bound compact producer proof, so archived payload bytes do not need to return to the hot path.

pub fn plugin_ingress_payload_matches( &self, id: IngressId, plugin: &str, packet_type: &str, occurred_at: SimTime, expected_payload: &Value, ) -> Result<bool, CanwuError>

Matches a retained plugin ingress to an exact provider payload and delivery time. Payload inspection is deliberately limited to retained records: archived receipts prove producer identity, but cannot safely be reused to authorize a different legal proposal without the original bytes.

pub fn decision_attempt( &self, request_id: DecisionRequestId, ) -> Result<Option<&DecisionAttemptRecord>, CanwuError>

Returns the retained outcome for one exact decision request.

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

Returns one current decision-controller binding after an explicit core read.

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

Returns one current decision ticket after an explicit core read.

Examples found in repository

examples/uncertainty_resolution.rs (line 27)

fn random_resolution_system(
    view: &SimulationView<'_>,
    context: &BoundaryContext,
) -> Result<BoundaryProposal, CanwuError> {
    let ticket = view
        .decision_ticket(RANDOM_TICKET)?
        .expect("the example opens the ticket before the daily boundary");
    let calendar_ingress = context
        .admitted_ingress
        .first()
        .copied()
        .expect("the example runs this system from calendar ingress");
    let option_weights = vec![
        DecisionOptionWeight::new("fail", 25),
        DecisionOptionWeight::new("pass", 75),
    ];
    let sample = view.random_sample_for_operation(
        &decision_stream(),
        EvidenceRef::Ingress(calendar_ingress),
        "decision_selection",
        "law-proposal-42",
        RandomOperationTarget::DecisionTicket {
            ticket_id: ticket.id,
            ticket_version: ticket.version,
        },
        0,
        100,
        "select whether the law passes from configured weights",
    )?;
    Ok(BoundaryProposal {
        directives: vec![BoundaryDirective::ResolveDecisionRandomly {
            resolution: RandomDecisionResolution {
                priority: 0,
                decision_request_id: DecisionRequestId::new(3),
                command_request_id: None,
                ticket_id: ticket.id,
                expected_version: ticket.version,
                controller_id: ticket.assigned_controller.clone(),
                sample,
                option_weights,
                tie_break: None,
            },
        }],
        ..BoundaryProposal::default()
    })
}

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

Examples found in repository

examples/governance_transition.rs (line 388)

fn audit_order(
    view: &SimulationView<'_>,
    context: &BoundaryContext,
) -> Result<BoundaryProposal, CanwuError> {
    if owned_order_ingress(view, context, CENTRAL_PLUGIN, ISSUE_INGRESS)?.is_some() {
        return Ok(BoundaryProposal::default());
    }
    let order = order_payload(view)?;
    for (label, reference, expected_plugin, expected_system) in [
        (
            "treasury",
            treasury_reference().as_untyped(),
            TREASURY_PLUGIN,
            "prepare-treasury",
        ),
        (
            "county",
            county_reference().as_untyped(),
            COUNTY_PLUGIN,
            "prepare-county",
        ),
    ] {
        let record = view.domain_record(reference)?.ok_or_else(|| {
            CanwuError::new(
                ErrorCode::InvalidBoundary,
                format!("central audit is missing the {label} relief disposition"),
            )
        })?;
        let expected_hash = action_hash(600)?;
        validate_order(&order, expected_system, expected_plugin, &expected_hash)?;
        let actual_hash = canonical_hash(ACTION_HASH_DOMAIN, &record.payload)?;
        if record.version != 1
            || !record.is_active()
            || record.owner != expected_plugin
            || actual_hash != expected_hash
            || record.payload != json!({"status": "committed", "grain_units": 600})
        {
            return Err(CanwuError::new(
                ErrorCode::InvalidBoundary,
                format!("central audit found an invalid {label} disposition"),
            ));
        }
    }
    Ok(BoundaryProposal::default())
}

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

where T: DomainRecordType,

Examples found in repository

examples/governance_transition.rs (line 211)

fn order_payload(view: &SimulationView<'_>) -> Result<ReliefOrder, CanwuError> {
    view.typed_domain_record(&order_reference())?
        .ok_or_else(|| CanwuError::new(ErrorCode::InvalidBoundary, "relief order is missing"))?
        .decode_payload::<ReliefOrderRecord>()
}

fn validate_order(
    order: &ReliefOrder,
    expected_system: &str,
    expected_plugin: &str,
    expected_hash: &str,
) -> Result<(), CanwuError> {
    let valid = order.order_id == ORDER_ID
        && order.issued_by == CENTRAL_PLUGIN
        && order.treasury_system == "prepare-treasury"
        && order.treasury_version == 1
        && order.treasury_disposition == "committed"
        && order.county_system == "prepare-county"
        && order.county_version == 1
        && order.county_disposition == "committed"
        && ((expected_plugin == TREASURY_PLUGIN
            && expected_system == "prepare-treasury"
            && order.treasury_hash == expected_hash)
            || (expected_plugin == COUNTY_PLUGIN
                && expected_system == "prepare-county"
                && order.county_hash == expected_hash));
    if !valid {
        return Err(CanwuError::new(
            ErrorCode::InvalidBoundary,
            format!("{expected_plugin} received an invalid relief manifest"),
        ));
    }
    Ok(())
}

fn publish_order(
    view: &SimulationView<'_>,
    context: &BoundaryContext,
) -> Result<BoundaryProposal, CanwuError> {
    let Some(order_id) = owned_order_ingress(view, context, CENTRAL_PLUGIN, ISSUE_INGRESS)? else {
        return Ok(BoundaryProposal::default());
    };
    if order_id != ORDER_ID {
        return Err(CanwuError::new(
            ErrorCode::InvalidBoundary,
            "the issue ingress names an unexpected relief order",
        ));
    }
    if view.typed_domain_record(&order_reference())?.is_some() {
        return Err(CanwuError::new(
            ErrorCode::InvalidBoundary,
            "the relief order already exists; duplicate issue ingress is invalid",
        ));
    }
    let treasury_hash = action_hash(600)?;
    let county_hash = action_hash(600)?;
    let manifest = DomainRecordDraft::from_typed(
        order_reference(),
        &ReliefOrder {
            order_id: ORDER_ID.to_owned(),
            issued_by: CENTRAL_PLUGIN.to_owned(),
            treasury_system: "prepare-treasury".to_owned(),
            treasury_version: 1,
            treasury_disposition: "committed".to_owned(),
            treasury_hash,
            county_system: "prepare-county".to_owned(),
            county_version: 1,
            county_disposition: "committed".to_owned(),
            county_hash,
        },
    )?;
    Ok(BoundaryProposal {
        directives: vec![
            BoundaryDirective::MutateRecord {
                mutation: DomainRecordMutation::Create { record: manifest },
                summary: "Publish the central relief order manifest".to_owned(),
            },
            BoundaryDirective::SchedulePluginIngress {
                target_plugin: TREASURY_PLUGIN.to_owned(),
                after: SimDuration::ZERO,
                packet_type: EXECUTE_INGRESS.to_owned(),
                priority: 0,
                payload: json!({"order_id": ORDER_ID}),
                affected: Vec::new(),
            },
            BoundaryDirective::SchedulePluginIngress {
                target_plugin: COUNTY_PLUGIN.to_owned(),
                after: SimDuration::ZERO,
                packet_type: EXECUTE_INGRESS.to_owned(),
                priority: 0,
                payload: json!({"order_id": ORDER_ID}),
                affected: Vec::new(),
            },
        ],
        ..BoundaryProposal::default()
    })
}

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

pub fn proposed_typed_domain_record<T>( &self, reference: &TypedDomainRecordRef<T>, ) -> Result<Option<&DomainRecord>, CanwuError>

where T: DomainRecordType,

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

Returns the exact evidence reference assigned to a domain-record version proposed earlier in the current boundary.

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

Returns the exact evidence reference for the currently visible version of a domain record. Strategic aggregation runs after atomic commit, therefore it cannot use Self::proposed_domain_record_version.

The current boundary overlay/proposal is preferred, followed by the runtime’s verified current-record provenance index. The index is maintained at commit time and rebuilt from canonical evidence on restore, so lookup does not scan retained or archived history.

pub fn domain_record_version_evidence_exists( &self, reference: &DomainRecordVersionRef, ) -> Result<bool, CanwuError>

Returns whether an exact domain-record version reference is valid at this proposal-visible cut.

This validates both the record identity/version and its establishment source. Earlier same-boundary proposals are considered before retained or archived runtime evidence. Either the exact record-kind read or the administrative domain-record read grants access.

pub fn domain_record_version_is_current( &self, reference: &DomainRecordVersionRef, ) -> Result<bool, CanwuError>

Checks that an exact domain-record version is both valid evidence and current.

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

Returns whether a generic evidence identity is retained or archived.

Domain-record versions proposed earlier in this boundary are visible. Archived identities count as existing even when their bodies are no longer retained.

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

Returns when retained or earlier same-boundary evidence first became authoritative at this proposal-visible cut.

Archived identity receipts do not retain a precise semantic time, so they return None and callers that require temporal ordering must fail closed or load the archived evidence body.

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

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

Archived receipts prove that a version existed but do not contain its body, so this returns None when the corresponding evidence segment is not live in the runtime.

pub fn domain_records_of_kind( &self, kind: &DomainRecordKind, limit: usize, ) -> Result<Vec<DomainRecord>, CanwuError>

Returns a bounded, deterministic projection of records of one kind.

Same-boundary overlays take precedence over current state. Records are ordered by their canonical reference, so result order is replay stable.

pub fn domain_records_of_kind_after( &self, kind: &DomainRecordKind, after: Option<&DomainRecordRef>, limit: usize, ) -> Result<Vec<DomainRecord>, CanwuError>

Returns one bounded deterministic page of records after a canonical record-reference cursor.

The cursor is exclusive and must name the same kind. This keeps plugin scans bounded without imposing a 10,000-record lifetime ceiling on a domain kind. Same-boundary overlays retain the same precedence as Self::domain_records_of_kind.

pub fn knowledge_changes_by_correlation( &self, plugin: &str, producer_correlation: &str, ) -> Result<Vec<BoundaryKnowledgeChange>, CanwuError>

Finds committed knowledge changes produced with an exact correlation.

This supports next-boundary operation finalization without granting a plugin unrestricted access to unrelated knowledge payloads.

pub fn knowledge_changes_by_correlation_prefix( &self, plugin: &str, producer_correlation_prefix: &str, ) -> Result<Vec<BoundaryKnowledgeChange>, CanwuError>

Finds committed knowledge changes whose producer correlation begins with a deterministic operation prefix.

The prefix remains plugin-scoped. This is intended for bounded multi-holder operation finalization where every holder batch must keep a unique full correlation value.

pub fn reservation( &self, reservation: &ReservationRef, ) -> Result<Option<&ReservationAllocation>, CanwuError>

Examples found in repository

examples/phased_boundary.rs (line 53)

fn apply_grain(
    view: &SimulationView<'_>,
    _context: &BoundaryContext,
) -> Result<BoundaryProposal, CanwuError> {
    let reservation = ReservationRef::new("example-demand", "request", "daily-grain");
    let allocation = view.reservation(&reservation)?.ok_or_else(|| {
        CanwuError::new(
            ErrorCode::InvalidBoundary,
            "the declared grain reservation did not produce allocation evidence",
        )
    })?;
    let territory = EntityRef::Territory(TerritoryId::new(1));
    Ok(BoundaryProposal {
        directives: vec![
            BoundaryDirective::SetComponent {
                state: StateKey::new("garrison", "grain"),
                entity: territory.clone(),
                component: "daily_grant".to_owned(),
                value: Value::from(allocation.granted),
                summary: format!(
                    "Granted {} grain to the western garrison",
                    allocation.granted
                ),
            },
            BoundaryDirective::Emit {
                event_type: "grain_allocated".to_owned(),
                summary: "The daily grain allocation settled".to_owned(),
                affected: vec![territory],
            },
        ],
        ..BoundaryProposal::default()
    })
}

pub fn random_range( &self, stream: &RandomStreamKey, upper_exclusive: u64, purpose: &str, ) -> Result<u64, CanwuError>

pub fn random_range_for_operation( &self, stream: &RandomStreamKey, evidence: EvidenceRef, operation_kind: &str, application_operation_id: &str, target: RandomOperationTarget, draw_slot: u32, upper_exclusive: u64, purpose: &str, ) -> Result<u64, CanwuError>

pub fn random_sample_for_operation( &self, stream: &RandomStreamKey, evidence: EvidenceRef, operation_kind: &str, application_operation_id: &str, target: RandomOperationTarget, draw_slot: u32, upper_exclusive: u64, purpose: &str, ) -> Result<RandomSample, CanwuError>

Examples found in repository

examples/uncertainty_resolution.rs (lines 38-50)

fn random_resolution_system(
    view: &SimulationView<'_>,
    context: &BoundaryContext,
) -> Result<BoundaryProposal, CanwuError> {
    let ticket = view
        .decision_ticket(RANDOM_TICKET)?
        .expect("the example opens the ticket before the daily boundary");
    let calendar_ingress = context
        .admitted_ingress
        .first()
        .copied()
        .expect("the example runs this system from calendar ingress");
    let option_weights = vec![
        DecisionOptionWeight::new("fail", 25),
        DecisionOptionWeight::new("pass", 75),
    ];
    let sample = view.random_sample_for_operation(
        &decision_stream(),
        EvidenceRef::Ingress(calendar_ingress),
        "decision_selection",
        "law-proposal-42",
        RandomOperationTarget::DecisionTicket {
            ticket_id: ticket.id,
            ticket_version: ticket.version,
        },
        0,
        100,
        "select whether the law passes from configured weights",
    )?;
    Ok(BoundaryProposal {
        directives: vec![BoundaryDirective::ResolveDecisionRandomly {
            resolution: RandomDecisionResolution {
                priority: 0,
                decision_request_id: DecisionRequestId::new(3),
                command_request_id: None,
                ticket_id: ticket.id,
                expected_version: ticket.version,
                controller_id: ticket.assigned_controller.clone(),
                sample,
                option_weights,
                tie_break: None,
            },
        }],
        ..BoundaryProposal::default()
    })
}

pub fn component( &self, state: &StateKey, entity: &EntityRef, component: &str, ) -> Result<Option<&Value>, CanwuError>

pub fn proposed_component( &self, state: &StateKey, entity: &EntityRef, component: &str, ) -> Result<Option<&Value>, CanwuError>

Trait Implementations

impl PluginArchiveObjectProvider for SimulationView<'_>

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