refactor: install the canister memories in create_execution_state by mraszyk · Pull Request #11142 · dfinity/ic

mraszyk · 2026-08-14T10:21:58Z

Hypervisor::create_execution_state always built the initial memories of the new Wasm module, and every caller then overwrote them afterwards: install_code swapped in the preserved memories in InstallCodeHelper::replace_execution_state_and_allocations, and load_canister_snapshot assigned the snapshot's memories directly. Which memories a new execution state ends up with was hence decided in three different places.

Make create_execution_state take a mandatory MemorySource describing where the memories come from (Fresh for install/reinstall, Preserve for upgrades, Explicit for snapshot restore) and apply it there, so it is the single place that assembles an execution state's memories.

The wasm_memory_persistence upgrade option only ever selected the main memory handling based on the install mode; the two enhanced orthogonal persistence checks in determine_main_memory_handling merely rejected otherwise valid combinations. Split it accordingly into the infallible main_memory_handling, which runs before the execution state is created, and validate_wasm_memory_persistence, which runs after it in the same position relative to the compilation charge as before.

load_canister_snapshot now builds the memories to restore before prepaying for the message. As a result a failure to load them (CanisterSnapshotNotLoadable) no longer charges the canister for compiling the snapshot's module and now takes precedence over NotEnoughCycles.

`Hypervisor::create_execution_state` always built the initial memories of the new Wasm module, and every caller then overwrote them afterwards: `install_code` swapped in the preserved memories in `InstallCodeHelper::replace_execution_state_and_allocations`, and `load_canister_snapshot` assigned the snapshot's memories directly. Which memories a new execution state ends up with was hence decided in three different places, none of which the type system forced a caller to visit. Make `create_execution_state` take a mandatory `MemorySource` describing where the memories come from (`Fresh` for install/reinstall, `Preserve` for upgrades, `Explicit` for snapshot restore) and apply it there, so it is the single place that assembles an execution state's memories. The `wasm_memory_persistence` upgrade option only ever selected the main memory handling based on the install mode; the two enhanced orthogonal persistence checks in `determine_main_memory_handling` merely rejected otherwise valid combinations. Split it accordingly into the infallible `main_memory_handling`, which runs before the execution state is created, and `validate_wasm_memory_persistence`, which runs after it in the same position relative to the compilation charge as before. `load_canister_snapshot` now builds the memories to restore before prepaying for the message. As a result a failure to load them (`CanisterSnapshotNotLoadable`) no longer charges the canister for compiling the snapshot's module and now takes precedence over `NotEnoughCycles`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Centralizes execution-state memory selection in Hypervisor::create_execution_state.

Changes:

Adds fresh, preserved, and explicit memory sources.
Simplifies install/upgrade memory handling and persistence validation.
Prepares snapshot memories before cycle prepayment.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`src/lib.rs`	Re-exports memory-handling APIs.
`src/hypervisor.rs`	Applies memory sources during state creation.
`src/execution/upgrade/tests.rs`	Updates stage documentation.
`src/execution/upgrade.rs`	Preserves upgrade memories and separates validation.
`src/execution/install.rs`	Uses fresh memories for installs.
`src/execution/install_code.rs`	Removes post-creation memory swapping.
`src/canister_manager.rs`	Prepares snapshot memories before charging.
`benches/management_canister/create_execution_state.rs`	Updates benchmark invocation.
`benches/lib/src/common.rs`	Updates benchmark helper invocation.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

mraszyk · 2026-08-14T12:41:54Z

+/// Specifies the handling of the canister's memories.
+/// * On install and re-install:
+///   - Replace both the stable memory and the main memory.
+/// * On upgrade:
+///   - For canisters with enhanced orthogonal persistence (Motoko):
+///     Retain both the main memory and the stable memory.
+///   - For all other canisters:
+///     Retain only the stable memory and erase the main memory.


Not sure about this one, the current formulation is indeed a bit imprecise (informal), but describes the intent (Motoko EOP).

I suppose you could reorder things as suggested, but retaining your existing structure:

Suggested change

/// Specifies the handling of the canister's memories.

/// * On install and re-install:

/// - Replace both the stable memory and the main memory.

/// * On upgrade:

/// - For canisters with enhanced orthogonal persistence (Motoko):

/// Retain both the main memory and the stable memory.

/// - For all other canisters:

/// Retain only the stable memory and erase the main memory.

/// Specifies the handling of the canister's memories.

/// * On install and re-install:

/// - Replace both the stable memory and the main memory.

/// * On upgrade:

/// - Stable memory: retained for all canisters.

/// - Main memory: retained for canisters with enhanced orthogonal persistence

/// (Motoko) when the validated persistence option is `Keep`; and erased in

/// all other cases.

Or you can stick with what you have. No strong opinion.

zeropath-ai · 2026-08-14T13:49:35Z

✅ No security or compliance issues detected. Reviewed everything up to 082f70c.

Security Overview

🔎 Scanned files: 9 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/f5e9d2bb-29a4-4b64-902a-391d65fd8b2d?scanId=378e9ef3-6838-4634-9a71-6e2f668c3906&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/execution_environment/benches/lib/src/common.rs • Add MemorySource::Fresh to ExecutionEnvironment create call ► rs/execution_environment/benches/management_canister/create_execution_state.rs • Import MemorySource • Pass MemorySource::Fresh to create_execution_state
Enhancement	► rs/execution_environment/src/canister_manager.rs • Import MemorySource from hypervisor • Build up snapshot memories up front for upgrade path (snapshot_wasm_memory, snapshot_stable_memory) and pass to create_execution_state via MemorySource::Explicit
Enhancement	► rs/execution_environment/src/execution/install.rs • Use MemorySource::Fresh when calling create_execution_state during install path
Enhancement	► rs/execution_environment/src/execution/install_code.rs • Remove MemoryHandling related struct usage in replace_execution_state_and_allocations signature and callsites (simplify to not pass memory_handling)
Enhancement	► rs/execution_environment/src/execution/upgrade.rs • Add MemorySource and MemoryHandling related imports • Introduce construction of new_memories via MemorySource::Preserve or MemorySource::Fresh for upgrade path • Replace direct memory handling logic with memory source flow and validation call • Remove direct MemoryHandling usage in upgrade path
Enhancement	► rs/execution_environment/src/execution/upgrade/tests.rs • Update test comments to reflect new validation flow and memory persistence checks
Enhancement	► rs/execution_environment/src/hypervisor.rs • Introduce MemoryHandling enum, CanisterMemoryHandling struct, and MemorySource enum to describe memory sourcing/persistence strategies (Fresh, Preserve, Explicit)
Enhancement	► rs/execution_environment/src/hypervisor.rs (MemorySource usage and handling in create_execution_state) • Extend Hypervisor::create_execution_state to apply MemorySource variants (Fresh, Preserve, Explicit) to execution state's memories
Enhancement	► rs/execution_environment/src/lib.rs • Re-export MemoryHandling, MemorySource, CanisterMemoryHandling alongside Hypervisor and others

alin-at-dfinity · 2026-08-14T14:03:53Z

+// is constructed once per operation and consumed right away.
+#[allow(clippy::large_enum_variant)]
+pub enum MemorySource<'a> {
+    /// Install and re-install: keep the initial memories of the new module.


"Keep" is potentially confusing in this context (particularly given that there's a Preserve variant below, with the exact opposite behavior).

Suggested change

/// Install and re-install: keep the initial memories of the new module.

/// Install and re-install: use the newly installed module's initial memories.

alin-at-dfinity · 2026-08-14T14:12:17Z

+/// Specifies the handling of the canister's memories.
+/// * On install and re-install:
+///   - Replace both the stable memory and the main memory.
+/// * On upgrade:
+///   - For canisters with enhanced orthogonal persistence (Motoko):
+///     Retain both the main memory and the stable memory.
+///   - For all other canisters:
+///     Retain only the stable memory and erase the main memory.


I suppose you could reorder things as suggested, but retaining your existing structure:

Suggested change

/// Specifies the handling of the canister's memories.

/// * On install and re-install:

/// - Replace both the stable memory and the main memory.

/// * On upgrade:

/// - For canisters with enhanced orthogonal persistence (Motoko):

/// Retain both the main memory and the stable memory.

/// - For all other canisters:

/// Retain only the stable memory and erase the main memory.

/// Specifies the handling of the canister's memories.

/// * On install and re-install:

/// - Replace both the stable memory and the main memory.

/// * On upgrade:

/// - Stable memory: retained for all canisters.

/// - Main memory: retained for canisters with enhanced orthogonal persistence

/// (Motoko) when the validated persistence option is `Keep`; and erased in

/// all other cases.

Or you can stick with what you have. No strong opinion.

github-actions Bot added the refactor label Aug 14, 2026

mraszyk and others added 2 commits August 14, 2026 12:23

docs: address review comments on memory source doc comments

00359da

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs: update the stage 2 comment on the preserved memories

082f70c

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

mraszyk requested a balanced review from Copilot August 14, 2026 12:34

Copilot started reviewing on behalf of mraszyk August 14, 2026 12:34 View session

Copilot AI reviewed Aug 14, 2026

View reviewed changes

mraszyk marked this pull request as ready for review August 14, 2026 13:48

mraszyk requested a review from a team as a code owner August 14, 2026 13:48

github-actions Bot added the @core-protocol label Aug 14, 2026

alin-at-dfinity approved these changes Aug 14, 2026

View reviewed changes

Navigation Menu

Uh oh!

refactor: install the canister memories in create_execution_state - #11142

refactor: install the canister memories in create_execution_state#11142
mraszyk wants to merge 3 commits into
masterfrom
mraszyk/create-execution-state-memory-source

mraszyk commented Aug 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mraszyk Aug 14, 2026

Uh oh!

alin-at-dfinity Aug 14, 2026

Uh oh!

zeropath-ai Bot commented Aug 14, 2026

Uh oh!

alin-at-dfinity Aug 14, 2026

Uh oh!

alin-at-dfinity Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	/// Install and re-install: keep the initial memories of the new module.
	/// Install and re-install: use the newly installed module's initial memories.

Uh oh!

Conversation

mraszyk commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

mraszyk Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

alin-at-dfinity Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

zeropath-ai Bot commented Aug 14, 2026

Uh oh!

alin-at-dfinity Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

alin-at-dfinity Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mraszyk commented Aug 14, 2026 •

edited

Loading