Struct MemoryRuntime 

pub struct MemoryRuntime<M: Memory> { /* private fields */ }

MemoryRuntime

Canonical owner of allocation bootstrap state for one backing memory.

The runtime owns its MemoryManager, allocation-ledger persistence, bootstrap lifecycle, committed allocation capability, opens, and diagnostics. Static linked-program declarations are supplied separately as one immutable SealedDeclarationSnapshot.

Each bootstrap attempt fallibly decodes its ledger record from persisted memory. Capacity-checked writes use Cell; diagnostics also read persisted memory directly.

M needs only Memory. The runtime does not require the backing memory to be Send, Sync, Clone, or 'static.

The host must supply exclusive backing custody: no other runtime, manager or raw IO may access the same backing while this runtime or any of its leases lives. Aliases hidden behind a generic Memory cannot be detected here. Drop every lease and the runtime before constructing a replacement on retained backing. Opens are exclusive within this runtime, including across warm bootstrap and authority verification.

Implementations

impl<M: Memory> MemoryRuntime<M>

pub fn verify_authority( &self, requirements: &SealedDeclarationSnapshot, authority: &str, ) -> Result<(), RuntimeAdoptionError>

Verify every logical request for one authority in the supplied requirements against this runtime’s current commitment.

Requests must match key and authority while retaining the host’s assigned ID. Other authorities and additional committed keys are ignored. An authority with no requirements rejects. Grants and application schema semantics are not revalidated. Success neither grants new access nor proves application lifecycle readiness.

impl<M: Memory> MemoryRuntime<M>

pub fn memory_allocations( &self, ) -> Result<MemoryAllocations, RuntimeDiagnosticError>

Measure all IDs with a fixed metadata read and bounded current bindings.

Reads at most 34,848 backing bytes. Never initializes stores, decodes the ledger, writes, grows memory, or advances a generation. Available before bootstrap; current provenance totals are then unavailable. Host labels and pool eligibility are projected separately from borrowed runtime bindings.

pub fn memory_allocation_summary( &self, ) -> Result<MemoryAllocationSummary, RuntimeDiagnosticError>

Measure numeric totals and binding partitions without constructing per-ID rows or copying keys, owners or pool metadata. Reads at most 34,848 metadata bytes; no ledger history, writes, growth, or generation changes occur.

impl<M: Memory> MemoryRuntime<M>

pub fn diagnostic_export( &self, ) -> Result<DiagnosticExport, RuntimeDiagnosticError>

Export this runtime’s recovered ledger and live virtual-memory sizes.

pub fn commit_recovery_diagnostic( &self, ) -> Result<CommitSnapshotDiagnostic, RuntimeDiagnosticError>

Diagnose protected commit recovery from this runtime’s ledger memory.

This operation is available before bootstrap when the stable-cell envelope is readable or the ledger memory is empty.

impl<M: Memory> MemoryRuntime<M>

pub fn new(memory: M) -> Result<Self, RuntimeConstructionError>

Construct an unbootstrapped runtime without overwriting foreign memory.

Empty backing memory is initialized as an ic_stable_structures::MemoryManager. Nonempty memory must pass bounded validation of the current manager header, bucket table, and extents; otherwise construction returns a typed error before the manager can write its header or allocation table. A pre-grown blank memory is nonempty and is therefore rejected rather than assumed disposable.

Errors

Returns RuntimeConstructionError::ForeignMemory for nonempty memory without MemoryManager magic, or RuntimeConstructionError::UnsupportedMemoryManagerVersion when the magic is recognized but the layout version is not current. Invalid metadata returns RuntimeConstructionError::Layout. Refused fresh metadata growth returns RuntimeConstructionError::Growth without writes, allowing the same backing memory to be retried. Reopening honors the actual persisted bucket size; only fresh memory uses 128 pages.

pub fn new_with_config( memory: M, config: MemoryManagerConfig, ) -> Result<Self, RuntimeConstructionError>

Construct with an explicit immutable bucket policy. Existing memory must match exactly; mismatches fail before manager initialization or writes.

Errors

Returns the construction errors described by Self::new, or RuntimeConstructionError::BucketSizeMismatch when existing geometry differs from config.

pub fn memory_manager_config(&self) -> MemoryManagerConfig

Return the immutable bucket configuration bound to this runtime’s manager.

pub const fn is_bootstrapped(&self) -> bool

Return whether this runtime has published committed allocation authority.

pub fn bootstrap<P: RuntimeBootstrapPolicy>( &mut self, declarations: &SealedDeclarationSnapshot, pool: &MemoryAllocationPool, policy: &P, ) -> Result<u64, RuntimeBootstrapError<P::Error>>

Bootstrap this backing memory from one immutable declaration snapshot.

Recovery, metadata admission, logical resolution, policy evaluation, staging, persistence and binding publication are local to this runtime. A repeated call is idempotent only when the sealed declaration snapshot, canonical host pool and RuntimeBootstrapPolicy::runtime_bootstrap_identity match the successful bootstrap. A mismatch returns a typed error without advancing the durable generation or re-evaluating policy. Independently sealed snapshots match when their canonical contents are equal.

Panics

Panics if a private runtime or encoding invariant is broken, or backing memory or a policy callback panics.

pub fn verify_bootstrap<P: RuntimeBootstrapPolicy>( &self, declarations: &SealedDeclarationSnapshot, pool: &MemoryAllocationPool, policy: &P, ) -> Result<u64, RuntimeBootstrapError<P::Error>>

Verify the exact host bootstrap binding through a shared runtime reference.

Returns the established generation only when declarations, pool and the policy identity match. Evaluates the policy identity once, but never runs admission or allocation validation, reads backing memory, writes, grows, or opens an allocation. An unbootstrapped runtime is refused rather than initialized. Hosts may share one committed runtime through Rc without reconstructing its binding checks or attempting mutable bootstrap again.

pub fn committed_allocations( &self, ) -> Result<&[AllocationDeclaration], RuntimeOpenError>

Borrow this runtime’s persisted application bindings without IO. These passive views cannot open memory independently of the runtime.

pub const fn committed_generation(&self) -> Result<u64, RuntimeOpenError>

Return the in-memory persisted generation without decoding the ledger.

pub const fn allocation_pool( &self, ) -> Result<&MemoryAllocationPool, RuntimeOpenError>

Borrow the host pool bound by successful bootstrap for host projections. This is current policy, never evidence of historical ownership or free IDs.

pub fn open_memory( &self, stable_key: &str, ) -> Result<RuntimeMemory<M>, RuntimeOpenError>

Lease by durable key using this runtime’s persisted current bindings.

A second live open returns RuntimeOpenError::AlreadyOpen without IO. Dropping the handle, or a collection that owns it, permits reopening.

pub fn memory_id(&self, stable_key: &str) -> Result<u8, RuntimeOpenError>

Resolve an application key’s committed ID without opening memory, reading history, or changing the host’s policy or bucket configuration.