Struct Simulation 

pub struct Simulation { /* private fields */ }

Implementations

impl Simulation

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

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

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

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 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>

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>

impl Simulation

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

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

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

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

Queues a plugin-owned internal ingress through an opaque capability returned by super::plugins::PluginRegistrar::register_internal_ingress.

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

Withdraws a pending plugin ingress item that the host enqueued through Self::enqueue_plugin_ingress.

The item must still be queued and strictly before its due time; otherwise (including archived IDs) the call fails with ErrorCode::LateIngress. Items of internal packet types require Self::cancel_permitted_plugin_ingress, and items scheduled inside the engine can be withdrawn only by their issuing plugin; both fail here 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 withdrawal is appended to the ingress journal as a terminal IngressPayload::PluginCancellation record; the returned receipt names that record. The withdrawn item is never admitted and never settles, and nothing is rolled back.

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

Withdraws a pending plugin ingress item of an internal packet type through the owning plugin’s opaque registration permit.

The permit must match the item’s exact plugin and packet type. It covers host-enqueued items of that type and items the same plugin scheduled inside the engine, but not items another plugin scheduled into this packet type. Timing and journal rules match Self::cancel_plugin_ingress.

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

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

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

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

impl Simulation

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

Asks every mandatory owner callback to author its own proposal and queues the resulting opaque commit as one canonical maintenance item.

impl Simulation

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

Converts this runtime into the opt-in compact journal interface.

Conversion itself preserves the complete retained history. Call CompactedSimulation::seal_evidence to release a validated segment explicitly.

pub fn prepare_paged_checkpoint( &self, source: Option<&PagedSimulationCheckpoint>, provider: &dyn StatePageProvider, ) -> Result<PreparedPagedSimulationCheckpoint, CanwuError>

Prepares an incremental content-addressed checkpoint without changing authoritative simulation state. Pages already readable from the provider are omitted from the delta.

pub fn portable_paged_checkpoint( &self, ) -> Result<PortablePagedSimulationCheckpoint, CanwuError>

Builds a self-contained paged checkpoint suitable for transfer between hosts without an external page provider.

pub fn from_paged_checkpoint( checkpoint: &PagedSimulationCheckpoint, provider: &dyn StatePageProvider, ) -> Result<Self, CanwuError>

Restores a simulation from a verified paged checkpoint. Current domain records are reconstructed from the committed Patricia roots; missing pages fail closed instead of being interpreted as absent state.

pub fn from_paged_checkpoint_and_journal( checkpoint: &PagedSimulationCheckpoint, provider: &dyn StatePageProvider, segments: Vec<EvidenceJournalSegment>, ) -> Result<Self, CanwuError>

Restores a paged current-state checkpoint after proving the contiguous evidence prefix named by its compact checkpoint metadata.

pub fn from_portable_paged_checkpoint( portable: PortablePagedSimulationCheckpoint, ) -> Result<Self, CanwuError>

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

Returns the current monotonic cut through every append-only journal.

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

Captures current authoritative state without cloning accumulated evidence.

pub fn archive_reachability_manifest( &self, retained_checkpoints: &[SimulationCheckpoint], page_retention: &StatePageRetentionLedger, decision_provider: &dyn DecisionArchiveProvider, plugin_provider: &dyn PluginArchiveObjectProvider, ) -> Result<ArchiveReachabilityManifest, CanwuError>

Builds the complete kernel and plugin mark set used before offline archive garbage collection. Every registered plugin participant is invoked automatically; callers cannot accidentally sweep a plugin archive by forgetting a second, manual manifest-extension step.

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

Clones only evidence appended after a previously persisted cursor.

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

Builds a portable full-save bundle with one segment from genesis.

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

Serializes the portable full-save checkpoint-journal bundle as JSON.

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

Restores a checkpoint after proving a contiguous journal prefix.

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

Restores a portable checkpoint-journal bundle.

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

Restores a bundle and rehydrates its exact executable plugin contracts.

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

Deserializes and restores a portable checkpoint-journal JSON bundle.

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

Deserializes a bundle and rehydrates its exact plugin contracts.

impl Simulation

pub fn person_availability( &self, person: PersonId, ) -> Option<&PersonAvailability>

Returns committed availability for a person. None means no change has been committed: the person is alive and free.

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

Returns every committed person availability in person-ID order.

impl Simulation

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

Replays only after the recorded engine, run, seed, and plugin manifests match, then verifies the final checkpoint commitment.

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

Replays with caller-owned package archive storage attached before any recorded boundary is evaluated. Cold idempotency and continuation checks therefore use the same authenticated provider during replay as they do during a live run.

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

Deserializes a Format 8 replay journal with recursive unknown-field rejection, then performs the exact environment-bound replay.

impl Simulation

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

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

pub fn advance_until<F>( &mut self, maximum: SimDuration, condition: F, ) -> Result<Vec<SimEvent>, CanwuError>

where F: FnMut(&Self) -> bool,

impl Simulation

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

impl Simulation

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

Registered transition manifests whose ready boundary has not settled, in manifest-ID order.

impl Simulation

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

Creates a simulation after validating that scenario references are sound.

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

Creates a simulation and activates the plugins required by initial application-defined records before returning a snapshot-capable runtime.

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

Creates a simulation with an exact, persisted run environment identity.

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

Creates a manifested run and activates all initial domain packages before the runtime can be observed or snapshotted.

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

Creates a run whose six policy dimensions are persisted and bound to the run-configuration artifact in run_manifest.

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

Creates a declared-policy run and activates all initial domain packages before the runtime can be observed or snapshotted.

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

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

pub const fn time(&self) -> SimTime

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

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

pub const 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; use the expected-time guard with external commands to detect clock and scheduled-work advancement.

pub fn run_manifest_hash(&self) -> &str

pub fn checkpoint_hash(&self) -> &str

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

Hash of simulated state and causal evidence. Run-purpose, controller, seat, observation, interaction, and trace policy remain save identity but are deliberately excluded from this authoritative result identity.

pub fn entities(&self) -> impl Iterator<Item = &EntityRef>

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

pub fn world(&self) -> WorldSnapshot

pub fn knowledge(&self) -> &KnowledgeSnapshot

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

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

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.

None means the evidence is missing or only its compact archive receipt remains. Proposed same-boundary evidence is available through SimulationView::evidence_time while its boundary is being built.

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

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

Returns None when the version is unavailable or only its compacted archive receipt remains.

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

Returns the exact evidence identity for the authoritative current version without manufacturing an initial-scenario source after compaction.

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

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 revision-bound page of authoritative domain records.

Pass the revision returned by the first page on every subsequent page. A mutation between pages is rejected instead of mixing two read cuts.

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

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 event_audience(&self, event: &SimEvent) -> EventAudience

Returns the persisted audience declaration for a plugin event.

Built-in event visibility remains part of the public actor-relative projection. Unlisted plugin event types deliberately resolve to EventAudience::Private.

pub fn replay_journal(&self) -> ReplayJournal

Panics

Panics only if a runtime object was constructed without its required Format 8 initial scenario, which is prevented by the public loaders.

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

Returns the durable external-delivery outbox derived from committed boundary emissions. Entries are deterministic and never re-sent by exact replay; the host owns delivery retries and acknowledgement.

pub fn snapshot(&self) -> SimulationSnapshot

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

pub fn from_snapshot(snapshot: SimulationSnapshot) -> Result<Self, CanwuError>

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

pub fn from_snapshot_with_plugins( snapshot: SimulationSnapshot, plugins: &[&dyn SimulationPlugin], ) -> Result<Self, CanwuError>

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

pub fn fork(&self) -> Self

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

Attaches the caller-owned provider used to resolve package cold archives during normal command admission, boundary settlement, and detached queries. The provider is executable host context and is never serialized into a snapshot.

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

Loads one package-owned archive object from the currently attached host provider. Callers must authenticate returned bytes against a committed package archive root before treating them as authoritative.