Milestone 4 - Step 1

codetracer-python-recorder/src/monitoring/api.rs: 
codetracer-python-recorder/src/monitoring/callbacks.rs: 
codetracer-python-recorder/src/monitoring/install.rs: 
codetracer-python-recorder/src/monitoring/mod.rs: 
codetracer-python-recorder/src/monitoring/tracer.rs: 
design-docs/codetracer-architecture-refactor-implementation-plan.status.md: 

Signed-off-by: Tzanko Matev <[email protected]>

Author: tzanko-matev

codetracer-python-recorder/src/monitoring/api.rs

@@ -0,0 +1,230 @@
+//! Monitoring API abstractions.
+
+use std::any::Any;
+
+use crate::code_object::CodeObjectWrapper;
+use pyo3::prelude::*;
+use pyo3::types::PyAny;
+
+use super::{CallbackOutcome, CallbackResult, EventSet, MonitoringEvents, NO_EVENTS};
+
+/// Trait implemented by tracing backends.
+///
+/// Each method corresponds to an event from `sys.monitoring`. Default
+/// implementations allow implementers to only handle the events they care
+/// about.
+///
+/// Every callback returns a `CallbackResult` so implementations can propagate
+/// Python exceptions or request that CPython disables future events for a
+/// location by yielding the `CallbackOutcome::DisableLocation` sentinel.
+pub trait Tracer: Send + Any {
+    /// Downcast support for implementations that need to be accessed
+    /// behind a `Box<dyn Tracer>` (e.g., for flushing/finishing).
+    fn as_any(&mut self) -> &mut dyn Any
+    where
+        Self: 'static,
+        Self: Sized,
+    {
+        self
+    }
+
+    /// Return the set of events the tracer wants to receive.
+    fn interest(&self, _events: &MonitoringEvents) -> EventSet {
+        NO_EVENTS
+    }
+
+    /// Called on Python function calls.
+    fn on_call(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _callable: &Bound<'_, PyAny>,
+        _arg0: Option<&Bound<'_, PyAny>>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called on line execution.
+    fn on_line(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _lineno: u32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when an instruction is about to be executed (by offset).
+    fn on_instruction(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when a jump in the control flow graph is made.
+    fn on_jump(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _destination_offset: i32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when a conditional branch is considered.
+    fn on_branch(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _destination_offset: i32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called at start of a Python function (frame on stack).
+    ///
+    /// Implementations should fail fast on irrecoverable conditions
+    /// (e.g., inability to access the current frame/locals) by
+    /// returning an error.
+    fn on_py_start(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Notify the tracer that an unrecoverable error occurred and the runtime
+    /// is transitioning into a detach/disable flow.
+    fn notify_failure(&mut self, _py: Python<'_>) -> PyResult<()> {
+        Ok(())
+    }
+
+    /// Called on resumption of a generator/coroutine (not via throw()).
+    fn on_py_resume(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called immediately before a Python function returns.
+    fn on_py_return(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _retval: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called immediately before a Python function yields.
+    fn on_py_yield(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _retval: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when a Python function is resumed by throw().
+    fn on_py_throw(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _exception: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when exiting a Python function during exception unwinding.
+    fn on_py_unwind(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _exception: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when an exception is raised (excluding STOP_ITERATION).
+    fn on_raise(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _exception: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when an exception is re-raised.
+    fn on_reraise(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _exception: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when an exception is handled.
+    fn on_exception_handled(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _exception: &Bound<'_, PyAny>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called on return from any non-Python callable.
+    fn on_c_return(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _callable: &Bound<'_, PyAny>,
+        _arg0: Option<&Bound<'_, PyAny>>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Called when an exception is raised from any non-Python callable.
+    fn on_c_raise(
+        &mut self,
+        _py: Python<'_>,
+        _code: &CodeObjectWrapper,
+        _offset: i32,
+        _callable: &Bound<'_, PyAny>,
+        _arg0: Option<&Bound<'_, PyAny>>,
+    ) -> CallbackResult {
+        Ok(CallbackOutcome::Continue)
+    }
+
+    /// Flush any buffered state to storage. Default is a no-op.
+    fn flush(&mut self, _py: Python<'_>) -> PyResult<()> {
+        Ok(())
+    }
+
+    /// Finish and close any underlying writers. Default is a no-op.
+    fn finish(&mut self, _py: Python<'_>) -> PyResult<()> {
+        Ok(())
+    }
+}

codetracer-python-recorder/src/monitoring/callbacks.rs

@@ -0,0 +1,3 @@
+//! sys.monitoring callback shims (Milestone 4 scaffolding).
+
+pub use super::{events_union, CallbackFn, CallbackOutcome, CallbackResult};

codetracer-python-recorder/src/monitoring/install.rs

@@ -0,0 +1,3 @@
+//! Tracer installation plumbing (Milestone 4 scaffolding).
+
+pub use super::tracer::{flush_installed_tracer, install_tracer, uninstall_tracer};

codetracer-python-recorder/src/monitoring/mod.rs

@@ -4,9 +4,13 @@ use pyo3::prelude::*;
 use pyo3::types::PyCFunction;
 use std::sync::OnceLock;
 
+pub mod api;
+pub mod callbacks;
+pub mod install;
 mod tracer;
 
-pub use tracer::{flush_installed_tracer, install_tracer, uninstall_tracer, Tracer};
+pub use api::Tracer;
+pub use install::{flush_installed_tracer, install_tracer, uninstall_tracer};
 
 const MONITORING_TOOL_NAME: &str = "codetracer";