WS1

design-docs/balanced-call-stack-events-implementation-plan.status.md: 

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

Author: tzanko-matev

codetracer-python-recorder/src/runtime/tracer/events.rs

@@ -158,8 +158,16 @@ pub(super) fn suppress_events() -> bool {
 
 impl Tracer for RuntimeTracer {
     fn interest(&self, events: &MonitoringEvents) -> EventSet {
-        // Minimal set: function start, step lines, and returns
-        events_union(&[events.PY_START, events.LINE, events.PY_RETURN])
+        // Balanced call stack requires tracking yields, resumes, throws, and unwinds
+        events_union(&[
+            events.PY_START,
+            events.PY_RETURN,
+            events.PY_YIELD,
+            events.PY_UNWIND,
+            events.PY_RESUME,
+            events.PY_THROW,
+            events.LINE,
+        ])
     }
 
     fn on_py_start(

design-docs/balanced-call-stack-events-implementation-plan.status.md

@@ -0,0 +1,38 @@
+# Balanced Call Stack Events – Status
+
+## Relevant Design Docs
+- `design-docs/adr/0012-balanced-call-stack-events.md`
+- `design-docs/balanced-call-stack-events-implementation-plan.md`
+- `design-docs/design-001.md` (monitoring architecture reference)
+
+## Key Source Files
+- `codetracer-python-recorder/src/runtime/tracer/events.rs`
+- `codetracer-python-recorder/src/monitoring/mod.rs`
+- `codetracer-python-recorder/src/monitoring/install.rs`
+- `codetracer-python-recorder/src/monitoring/callbacks.rs`
+- `codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs`
+- `codetracer-python-recorder/tests/python/test_monitoring_events.py`
+- `codetracer-python-recorder/tests/rust/print_tracer.rs`
+
+## Workstream Progress
+
+### WS1 – Monitoring Mask & Callback Wiring
+- **Scope recap:** Update `RuntimeTracer::interest` to include `PY_YIELD`, `PY_UNWIND`, `PY_RESUME`, and `PY_THROW`; ensure installer wiring respects the expanded mask; document the call/return mapping in `design-001`.
+- **Status:** _Completed_
+  - `RuntimeTracer::interest` now subscribes to the four additional events plus `LINE`.
+  - `design-docs/design-001.md` documents the call vs return mapping and clarifies how each event is encoded.
+  - Verification: `just test codetracer-python-recorder --all-targets` (passes).
+
+### WS2 – Call/Return Edge Helpers
+- **Status:** Not started (awaiting WS1 completion).
+
+### WS3 – Activation & Lifecycle Behaviour
+- **Status:** Not started.
+
+### WS4 – Testing & Validation
+- **Status:** Not started.
+
+## Next Checkpoints
+1. Modify `RuntimeTracer::interest` and related tests to assert the expanded mask.
+2. Update `design-docs/design-001.md` to document the event-to-writer mapping.
+3. Capture verification notes (e.g., `just test codetracer-python-recorder --all-targets`) once WS1 lands.

design-docs/design-001.md

@@ -157,12 +157,14 @@ allowing tracers to implement just the methods they care about.
 
 Each bullet below represents a low-level operation translating a single `sys.monitoring` event into the `runtime_tracing` stream.
 
+To keep the trace stack balanced we subscribe to `PY_START`, `PY_RESUME`, `PY_RETURN`, `PY_YIELD`, `PY_UNWIND`, `PY_THROW`, and `LINE`. `PY_START`/`PY_RESUME`/`PY_THROW` map to `TraceWriter::register_call`, while `PY_RETURN`/`PY_YIELD`/`PY_UNWIND` map to `TraceWriter::register_return`.
+
 ### Control Flow
 - **PY_START** – Create a `Function` event for the code object and push a new activation ID onto the thread's stack.
   ```rs
   pub fn on_py_start(code: PyObject, instruction_offset: i32);
   ```
-- **PY_RESUME** – Emit an `Event` log noting resumption and update the current activation's state.
+- **PY_RESUME** – Emit `TraceWriter::register_call` for the suspended activation (empty argument vector; CPython does not expose the `send()` payload) and update the current activation's state.
   ```rs
   pub fn on_py_resume(code: PyObject, instruction_offset: i32);
   ```
@@ -171,19 +173,19 @@ Each bullet below represents a low-level operation translating a single `sys.mon
   pub struct ReturnRecord { pub activation: ActivationId, pub value: Option<ValueRecord> }
   pub fn on_py_return(code: PyObject, instruction_offset: i32, retval: *mut PyObject);
   ```
-- **PY_YIELD** – Record a `Return` event flagged as a yield and keep the activation on the stack for later resumes.
+- **PY_YIELD** – Call `TraceWriter::register_return` with the yielded value (subject to value-capture policy), mark it as a yield, and keep the activation on the stack for later resumes.
   ```rs
   pub fn on_py_yield(code: PyObject, instruction_offset: i32, retval: *mut PyObject);
   ```
 - **STOP_ITERATION** – Emit an `Event` indicating iteration exhaustion for the current activation.
   ```rs
   pub fn on_stop_iteration(code: PyObject, instruction_offset: i32, exception: *mut PyObject);
   ```
-- **PY_UNWIND** – Mark the beginning of stack unwinding and note the target handler in an `Event`.
+- **PY_UNWIND** – Treat as a return edge by calling `TraceWriter::register_return` with the active exception so the activation closes even when an exception propagates.
   ```rs
   pub fn on_py_unwind(code: PyObject, instruction_offset: i32, exception: *mut PyObject);
   ```
-- **PY_THROW** – Emit an `Event` describing the thrown value and the target generator/coroutine.
+- **PY_THROW** – Emit `TraceWriter::register_call` for the resumed activation and include a single argument named `exception` whose value is the thrown object.
   ```rs
   pub fn on_py_throw(code: PyObject, instruction_offset: i32, exception: *mut PyObject);
   ```