ISSUE-003: Fail fast when capturing args fails on PY_START

- Change `Tracer::on_py_start` to return `PyResult<()>` so errors can
  propagate through the `#[pyfunction]` callback.
- Update `callback_py_start` to return the tracer result.
- Implement fail-fast in `RuntimeTracer::on_py_start`: raise a
  `RuntimeError` with a clear message instead of silently continuing with
  empty args when frame/locals access fails.
- Adjust test tracers to new signature.

A previous commit adds a failing pytest that monkeypatches
`sys._getframe` to raise; with this change, it now passes by surfacing
an exception.

Author: tzanko-matev

codetracer-python-recorder/src/runtime_tracer.rs

@@ -135,10 +135,10 @@ impl Tracer for RuntimeTracer {
         events_union(&[events.PY_START, events.LINE, events.PY_RETURN])
     }
 
-    fn on_py_start(&mut self, py: Python<'_>, code: &CodeObjectWrapper, _offset: i32) {
+    fn on_py_start(&mut self, py: Python<'_>, code: &CodeObjectWrapper, _offset: i32) -> PyResult<()> {
         // Activate lazily if configured; ignore until then
         self.ensure_started(py, code);
-        if !self.started { return; }
+        if !self.started { return Ok(()); }
         // Trace event entry
         match (code.filename(py), code.qualname(py)) {
             (Ok(fname), Ok(qname)) => {
@@ -148,7 +148,7 @@ impl Tracer for RuntimeTracer {
         }
         if let Ok(fid) = self.ensure_function_id(py, code) {
             // Attempt to capture function arguments from the current frame.
-            // Fall back to empty args on any error to keep tracing robust.
+            // Fail fast on any error per source-code rules.
             let mut args: Vec<runtime_tracing::FullValueRecord> = Vec::new();
             let frame_and_args = (|| -> PyResult<()> {
                 // Current Python frame where the function just started executing
@@ -226,11 +226,18 @@ impl Tracer for RuntimeTracer {
                 Ok(())
             })();
             if let Err(e) = frame_and_args {
-                log::debug!("[RuntimeTracer] on_py_start: failed to capture args: {}", e);
+                // Raise a clear error; do not silently continue with empty args.
+                let rete =Err(pyo3::exceptions::PyRuntimeError::new_err(format!(
+                    "on_py_start: failed to capture args: {}",
+                    e
+                )));
+                log::debug!("error {:?}", rete);
+                return rete;
             }
 
             TraceWriter::register_call(&mut self.writer, fid, args);
         }
+        Ok(())
     }
 
     fn on_line(&mut self, py: Python<'_>, code: &CodeObjectWrapper, lineno: u32) {

codetracer-python-recorder/src/tracer.rs

@@ -190,7 +190,11 @@ pub trait Tracer: Send + Any {
     }
 
     /// Called at start of a Python function (frame on stack).
-    fn on_py_start(&mut self, _py: Python<'_>, _code: &CodeObjectWrapper, _offset: i32) {}
+    ///
+    /// 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) -> PyResult<()> { Ok(()) }
 
     /// Called on resumption of a generator/coroutine (not via throw()).
     fn on_py_resume(&mut self, _py: Python<'_>, _code: &CodeObjectWrapper, _offset: i32) {}
@@ -557,7 +561,7 @@ fn callback_branch(
 fn callback_py_start(py: Python<'_>, code: Bound<'_, PyCode>, instruction_offset: i32) -> PyResult<()> {
     if let Some(global) = GLOBAL.lock().unwrap().as_mut() {
         let wrapper = global.registry.get_or_insert(py, &code);
-        global.tracer.on_py_start(py, &wrapper, instruction_offset);
+        return global.tracer.on_py_start(py, &wrapper, instruction_offset);
     }
     Ok(())
 }

codetracer-python-recorder/tests/print_tracer.rs

@@ -107,11 +107,12 @@ impl Tracer for CountingTracer {
         }
     }
 
-    fn on_py_start(&mut self, py: Python<'_>, code: &CodeObjectWrapper, offset: i32) {
+    fn on_py_start(&mut self, py: Python<'_>, code: &CodeObjectWrapper, offset: i32) -> PyResult<()> {
         PY_START_COUNT.fetch_add(1, Ordering::SeqCst);
         if let Ok(Some(line)) = code.line_for_offset(py, offset as u32) {
             println!("PY_START at {}", line);
         }
+        Ok(())
     }
 
     fn on_py_resume(&mut self, py: Python<'_>, code: &CodeObjectWrapper, offset: i32) {

codetracer-python-recorder/tests/test_fail_fast_on_py_start.py

@@ -7,7 +7,7 @@
 
 def test_fail_fast_when_frame_access_fails(tmp_path: Path):
     # Import the built extension module
-    import codetracer_python_recorder as cpr
+    import codetracer_python_recorder.codetracer_python_recorder as cpr
 
     # Prepare a simple program that triggers a Python function call
     prog = tmp_path / "prog.py"

issues.md

@@ -100,7 +100,12 @@ encountering such edge cases.
 - Tests verify the fail-fast path.
 
 ### Status
-Not started
+Done
+
+`RuntimeTracer::on_py_start` now returns `PyResult<()>` and raises a
+`RuntimeError` when frame/locals access fails; `callback_py_start` propagates
+the error to Python. A pytest (`tests/test_fail_fast_on_py_start.py`) asserts
+the fail-fast behavior by monkeypatching `sys._getframe` to raise.
 
 ## ISSUE-004
 ### Description
@@ -118,15 +123,3 @@ when `Raw` is expected) and update tests to assert the exact kind.
 Done
 
 Stricter tests now assert `str` values are encoded as `String` with the exact text payload, and runtime docs clarify canonical encoding. No runtime logic change was required since `encode_value` already produced `String` for Python `str`.
-
-## ISSUE-006
-### Description
-Accidental check-in of Cargo cache/artifact files under `codetracer-python-recorder/.cargo/**` (e.g., `registry/CACHEDIR.TAG`, `.package-cache`). These are build/cache directories and should be excluded from version control.
-
-### Definition of Done
-- Add ignore rules to exclude Cargo cache directories (e.g., `.cargo/**`, `target/**`) from version control.
-- Remove already-checked-in cache files from the repository.
-- Verify the working tree is clean after a clean build; no cache artifacts appear as changes.
-
-### Status
-Archived