refactor: move event handling interface to core

air/src/trace/mod.rs

@@ -6,12 +6,9 @@ pub use rows::{RowIndex, RowIndexError};
 
 mod main_trace;
 pub use main_trace::{MainTrace, MainTraceRow};
-
 // CONSTANTS
 // ================================================================================================
-
-/// The minimum length of the execution trace. This is the minimum required to support range checks.
-pub const MIN_TRACE_LEN: usize = 64;
+pub use miden_core::execution::MIN_TRACE_LEN;
 
 // MAIN TRACE LAYOUT
 // ------------------------------------------------------------------------------------------------

core/Cargo.toml

@@ -34,6 +34,7 @@ std = [
     "miden-crypto/std",
     "miden-debug-types/std",
     "miden-formatting/std",
+    "miden-utils-diagnostics/std",
     "miden-utils-indexing/std",
     "miden-utils-sync/std",
     "thiserror/std",
@@ -54,6 +55,7 @@ miden-crypto.workspace = true
 miden-debug-types.workspace = true
 miden-formatting.workspace = true
 miden-utils-core-derive.workspace = true
+miden-utils-diagnostics.workspace = true
 miden-utils-indexing.workspace = true
 miden-utils-sync.workspace = true
 

core/src/advice/mod.rs

@@ -2,7 +2,7 @@ use alloc::vec::Vec;
 
 use crate::{
     Felt, Word,
-    crypto::merkle::MerkleStore,
+    crypto::merkle::{InnerNodeInfo, MerkleStore},
     serde::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable},
 };
 
@@ -12,6 +12,31 @@ pub use map::AdviceMap;
 mod stack;
 pub use stack::AdviceStack;
 
+/// Maximum number of elements allowed on the advice stack. Set to 2^17.
+pub const MAX_ADVICE_STACK_SIZE: usize = 1 << 17;
+
+/// A declarative change to advice data requested by an event handler.
+#[derive(Debug, PartialEq, Eq)]
+pub enum AdviceMutation {
+    ExtendStack { stack: AdviceStack },
+    ExtendMap { other: AdviceMap },
+    ExtendMerkleStore { infos: Vec<InnerNodeInfo> },
+}
+
+impl AdviceMutation {
+    pub fn extend_advice_stack(stack: AdviceStack) -> Self {
+        Self::ExtendStack { stack }
+    }
+
+    pub fn extend_map(other: AdviceMap) -> Self {
+        Self::ExtendMap { other }
+    }
+
+    pub fn extend_merkle_store(infos: impl IntoIterator<Item = InnerNodeInfo>) -> Self {
+        Self::ExtendMerkleStore { infos: Vec::from_iter(infos) }
+    }
+}
+
 // ADVICE INPUTS
 // ================================================================================================
 

core/src/events/compatibility.rs

@@ -0,0 +1,171 @@
+//! Migration guide and temporary compatibility interface for event handlers.
+//!
+//! Event-handler interfaces moved from `miden-processor` to `miden-core`. The deprecated methods
+//! in this module preserve common existing handler implementations during the transition; they do
+//! not reproduce the complete former `ProcessorState` interface.
+//!
+//! # Imports
+//!
+//! Existing handlers can migrate from:
+//!
+//! ```rust,ignore
+//! use miden_processor::{
+//!     ProcessorState,
+//!     advice::AdviceMutation,
+//!     event::{EventError, EventHandler},
+//! };
+//! ```
+//!
+//! to:
+//!
+//! ```rust,ignore
+//! use miden_core::{
+//!     advice::AdviceMutation,
+//!     events::{EventContext, EventError, EventHandler},
+//! };
+//! ```
+//!
+//! # Accessor changes
+//!
+//! | Previous accessor | Replacement |
+//! | --- | --- |
+//! | `get_stack_item(position)` | `stack_item(position)` |
+//! | `get_stack_word(start)` | `stack_word(start)` |
+//! | `get_stack_state()` | `stack_snapshot()` |
+//! | `get_mem_value(context, address)` | `memory_value(address)` |
+//! | `get_mem_word(context, address)` | `memory_word(address)` |
+//! | `get_mem_state(context)` | `memory_snapshot()` |
+//! | `get_mem_addr_range(start, end)` | `memory_range_from_stack(start, end)` |
+//! | `advice_provider().stack()` | `advice_stack_snapshot()` |
+//! | `advice_provider().map()` | `advice_map()` |
+//! | `advice_provider().get_mapped_values(key)` | `advice_map_entry(key)` |
+//! | `advice_provider().get_tree_node(...)` | `advice_tree_node(...)` |
+//! | `get_stack_item(0)` for the event identity | `event_id()` |
+//!
+//! New memory accessors always read the active execution context, so handlers no longer obtain or
+//! pass a `ContextId`. The compatibility memory methods retain their old parameters but ignore the
+//! supplied context and read active-context memory.
+//!
+//! `stack_snapshot()`, `memory_snapshot()`, and `advice_stack_snapshot()` allocate owned snapshots.
+//!
+//! # Intentional differences
+//!
+//! - `clock()` returns `u32` rather than `miden_air::trace::RowIndex`.
+//! - The complete concrete `AdviceProvider` interface is not exposed.
+//! - Optional deferred-state lookup methods are not preserved.
+//! - Execution-options access is reserved for Miden's built-in precompile handlers and hidden from
+//!   the public handler documentation.
+//!
+//! # Example
+//!
+//! Before:
+//!
+//! ```rust,ignore
+//! fn handle(process: &ProcessorState<'_>) -> Result<Vec<AdviceMutation>, EventError> {
+//!     let event = EventId::from_felt(process.get_stack_item(0));
+//!     let context = process.ctx();
+//!     let value = process.get_mem_value(context, 0);
+//!     let advice = process.advice_provider().get_mapped_values(&process.get_stack_word(1));
+//!     // ...
+//! }
+//! ```
+//!
+//! After:
+//!
+//! ```rust,ignore
+//! fn handle(context: &EventContext<'_>) -> Result<Vec<AdviceMutation>, EventError> {
+//!     let event = context.event_id();
+//!     let value = context.memory_value(0);
+//!     let advice = context.advice_map_entry(&context.stack_word(1));
+//!     // ...
+//! }
+//! ```
+
+use alloc::vec::Vec;
+
+use super::{EventContext, EventContextProvider, EventError};
+use crate::{ContextId, Felt, MemoryAddress, MemoryError, Word, advice::AdviceMap};
+
+impl<'a> EventContext<'a> {
+    #[deprecated(note = "use EventContext::stack_item")]
+    pub fn get_stack_item(&self, position: usize) -> Felt {
+        self.stack_item(position)
+    }
+
+    #[deprecated(note = "use EventContext::stack_word")]
+    pub fn get_stack_word(&self, start: usize) -> Word {
+        self.stack_word(start)
+    }
+
+    #[deprecated(note = "use EventContext::stack_snapshot; it returns an allocated snapshot")]
+    pub fn get_stack_state(&self) -> Vec<Felt> {
+        self.stack_snapshot()
+    }
+
+    #[deprecated(note = "new handlers do not need an execution context identifier")]
+    pub fn ctx(&self) -> ContextId {
+        self.compatibility_context_id
+    }
+
+    #[deprecated(note = "use EventContext::memory_value; it reads active-context memory")]
+    pub fn get_mem_value(&self, _context: ContextId, address: u32) -> Option<Felt> {
+        self.memory_value(address)
+    }
+
+    #[deprecated(note = "use EventContext::memory_word; it reads active-context memory")]
+    pub fn get_mem_word(
+        &self,
+        _context: ContextId,
+        address: u32,
+    ) -> Result<Option<Word>, MemoryError> {
+        self.memory_word(address)
+    }
+
+    #[deprecated(
+        note = "use EventContext::memory_snapshot; it returns an allocated active-context snapshot"
+    )]
+    pub fn get_mem_state(&self, _context: ContextId) -> Vec<(MemoryAddress, Felt)> {
+        self.memory_snapshot()
+    }
+
+    #[deprecated(note = "use EventContext::memory_range_from_stack")]
+    pub fn get_mem_addr_range(
+        &self,
+        start_position: usize,
+        end_position: usize,
+    ) -> Result<core::ops::Range<u32>, MemoryError> {
+        self.memory_range_from_stack(start_position, end_position)
+    }
+
+    #[allow(deprecated)]
+    #[deprecated(note = "use EventContext advice accessors directly")]
+    pub fn advice_provider(&self) -> AdviceProviderView<'a> {
+        AdviceProviderView { provider: self.provider }
+    }
+}
+
+/// Temporary read-only compatibility view for handlers that accessed the advice provider directly.
+#[deprecated(note = "use EventContext advice accessors directly")]
+pub struct AdviceProviderView<'a> {
+    provider: &'a dyn EventContextProvider,
+}
+
+#[allow(deprecated)]
+impl<'a> AdviceProviderView<'a> {
+    /// Returns an allocated snapshot of the advice stack.
+    pub fn stack(&self) -> Vec<Felt> {
+        self.provider.advice_stack_snapshot()
+    }
+
+    pub fn map(&self) -> &'a AdviceMap {
+        self.provider.advice_map()
+    }
+
+    pub fn get_mapped_values(&self, key: &Word) -> Option<&'a [Felt]> {
+        self.provider.advice_map_entry(key)
+    }
+
+    pub fn get_tree_node(&self, root: Word, depth: Felt, index: Felt) -> Result<Word, EventError> {
+        self.provider.advice_tree_node(root, depth, index)
+    }
+}

processor/src/host/debug.rs → core/src/events/debug.rs

@@ -4,7 +4,7 @@ use alloc::{
 };
 use core::fmt;
 
-use miden_core::Felt;
+use crate::Felt;
 
 // WRITER IMPLEMENTATIONS
 // ================================================================================================
@@ -137,9 +137,8 @@ pub fn format_value<T: ToString>(value: Option<T>) -> String {
 mod tests {
     use alloc::{string::String, vec};
 
-    use miden_core::Felt;
-
     use super::{format_value, write_interval, write_stack};
+    use crate::Felt;
 
     #[test]
     fn write_stack_full_uses_tree_style() {