Start-Agent-Branch: tracer-trait

Target-Remote: https://github.com/metacraft-labs/codetracer-python-recorder.git

Author: tzanko-matev

.agents/tasks/2025/08/18-1208-tracer-trait

@@ -0,0 +1,73 @@
+1. Create a trait for a tracer implemented using the Python monitoring API. The methods of the trait should correspond to the events that one can subscribe to via the API.
+
+Here's a sketch of the design of the trait. We want to support tracers which implement only some of the methods.
+
+``rs
+use bitflags::bitflags;
+
+bitflags! {
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    pub struct EventMask: u32 {
+        const CALL       = 1 << 0;
+        //CODEX: write this
+        ...
+    }
+}
+
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Event {
+    Call,
+    //CODEX: write this
+    ...
+    // Non-exhaustive for forward compatibility.
+}
+
+pub trait Tracer: Send {
+    /// Tell the dispatcher what you want to receive. Default: nothing (fast path).
+    fn interest(&self) -> EventMask { EventMask::empty() }
+
+    // Default no-ops let implementers pick only what they need.
+    fn on_call(&mut self, ...) {}
+    //CODEX: write this
+}
+
+// Example tracer: only cares about CALL.
+struct CallsOnly;
+impl Tracer for CallsOnly {
+    fn interest(&self) -> EventMask { EventMask::CALL | ... }
+    fn on_call(&mut self, ...)  { println!("call:   {:?}", ...); }
+    ...
+}
+
+// Dispatcher checks the mask to avoid vtable calls it doesn’t need.
+pub struct Dispatcher {
+    tracer: Box<dyn Tracer>,
+    mask: EventMask,
+}
+
+impl Dispatcher {
+    pub fn new(tracer: Box<dyn Tracer>) -> Self {
+        let mask = tracer.interest();
+        Self { tracer, mask }
+    }
+
+    pub fn dispatch_call(&mut self, ...) {
+        if self.mask.contains(EventMask::CALL) {
+            self.tracer.on_call(...);
+        }
+        
+    }
+    // CODEX: ... same for other events
+}
+``
+
+2. Create code which takes a trait implementation and hooks it to the global tracing. Follow the design-docs for the specific API that needs to be implemented. 
+
+3. Create a test implementation of the trait which prints text to stdout. Run the test implementation. Note that the test implementation should not be included in the final build 
+artefact, it will be used only for testing.
+
+4. Update the testing framework to be able to use `just test` also for Rust tests. Specifically we want to run our test implementation from point 2. using `just test`
+
+Refer to the design-docs folder for the current planned design. Add/update files in the folder to match what was implemented in this task.
+