WS2-2

codetracer-python-recorder/README.md: 
codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs: 
codetracer-python-recorder/tests/python/test_monitoring_events.py: 
design-docs/module-call-event-naming-implementation-plan.status.md: 

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

Author: tzanko-matev

codetracer-python-recorder/README.md

@@ -82,6 +82,12 @@ selector = "arg:literal:debug_payload"
 action = "drop"
 ```
 
+## Trace naming semantics
+
+- Module-level activations no longer appear as the ambiguous `<module>` label. When the recorder sees `co_qualname == "<module>"`, it derives the actual dotted package name (e.g., `<my_pkg.mod>` or `<boto3.session>`) using project roots, `sys.modules`, and frame metadata.
+- The angle-bracket convention remains for module entries so downstream tooling can distinguish top-level activations at a glance.
+- Traces will still emit `<module>` for synthetic filenames (`<stdin>`, `<string>`), frozen/importlib bootstrap frames, or exotic loaders that omit filenames entirely. This preserves previous behaviour when no reliable name exists.
+
 ## Packaging expectations
 
 Desktop installers add the wheel to `PYTHONPATH` before invoking the user’s

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

@@ -157,6 +157,13 @@ impl RuntimeTracer {
     }
 }
 
+#[cfg(test)]
+impl RuntimeTracer {
+    fn function_name_for_test(&self, py: Python<'_>, code: &CodeObjectWrapper) -> PyResult<String> {
+        self.function_name(py, code)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1072,52 +1079,42 @@ sensitive("s3cr3t")
     #[test]
     fn module_import_records_module_name() {
         Python::with_gil(|py| {
-            ensure_test_module(py);
-
-            let mut tracer =
-                RuntimeTracer::new("runner.py", &[], TraceEventsFileFormat::Json, None, None);
-
             let project = tempfile::tempdir().expect("project dir");
             let pkg_root = project.path().join("lib");
             let pkg_dir = pkg_root.join("my_pkg");
             fs::create_dir_all(&pkg_dir).expect("create package dir");
-            fs::write(pkg_dir.join("__init__.py"), "\n").expect("write __init__");
-            fs::write(
-                pkg_dir.join("mod.py"),
-                "value = 1\nprint('imported module value', value)\n",
-            )
-            .expect("write module file");
+            let module_path = pkg_dir.join("mod.py");
+            fs::write(&module_path, "value = 1\n").expect("write module file");
 
-            let script = format!(
-                "import sys\nsys.path.insert(0, r\"{root}\")\nimport my_pkg.mod\n",
-                root = pkg_root.display()
-            );
+            let sys = py.import("sys").expect("import sys");
+            let sys_path = sys.getattr("path").expect("sys.path");
+            sys_path
+                .call_method1("insert", (0, pkg_root.to_string_lossy().as_ref()))
+                .expect("insert temp root");
 
-            {
-                let _guard = ScopedTracer::new(&mut tracer);
-                LAST_OUTCOME.with(|cell| cell.set(None));
-                let script_c = CString::new(script).expect("script contains nul byte");
-                py.run(script_c.as_c_str(), None, None)
-                    .expect("execute module import");
-            }
+            let tracer =
+                RuntimeTracer::new("runner.py", &[], TraceEventsFileFormat::Json, None, None);
 
-            let function_records: Vec<String> = tracer
-                .writer
-                .events
-                .iter()
-                .filter_map(|event| {
-                    if let TraceLowLevelEvent::Function(record) = event {
-                        Some(record.name.clone())
-                    } else {
-                        None
-                    }
-                })
-                .collect();
+            let builtins = py.import("builtins").expect("builtins");
+            let compile = builtins.getattr("compile").expect("compile builtin");
+            let code_obj: Bound<'_, PyCode> = compile
+                .call1((
+                    "value = 1\n",
+                    module_path.to_string_lossy().as_ref(),
+                    "exec",
+                ))
+                .expect("compile module code")
+                .downcast_into()
+                .expect("PyCode");
 
-            assert!(
-                function_records.iter().any(|name| name == "<my_pkg.mod>"),
-                "expected module function name to be rewritten: {function_records:?}"
-            );
+            let wrapper = CodeObjectWrapper::new(py, &code_obj);
+            let resolved = tracer
+                .function_name_for_test(py, &wrapper)
+                .expect("derive function name");
+
+            assert_eq!(resolved, "<my_pkg.mod>");
+
+            sys_path.call_method1("pop", (0,)).expect("pop temp root");
         });
     }
 

codetracer-python-recorder/tests/python/test_monitoring_events.py

@@ -196,6 +196,32 @@ def arg_value(i: int) -> Dict[str, Any]:
     assert v1.get("text") == "x"
 
 
+def test_module_imports_record_package_names(tmp_path: Path) -> None:
+    pkg_root = tmp_path / "lib"
+    pkg_dir = pkg_root / "my_pkg"
+    pkg_dir.mkdir(parents=True)
+    (pkg_dir / "__init__.py").write_text("", encoding="utf-8")
+    (pkg_dir / "mod.py").write_text("VALUE = 1\n", encoding="utf-8")
+
+    runner = tmp_path / "runner.py"
+    runner.write_text(
+        f"import sys\nsys.path.insert(0, r\"{pkg_root}\")\nimport my_pkg.mod\n",
+        encoding="utf-8",
+    )
+
+    out_dir = ensure_trace_dir(tmp_path)
+    session = codetracer.start(out_dir, format=codetracer.TRACE_JSON, start_on_enter=runner)
+    try:
+        runpy.run_path(str(runner), run_name="__main__")
+    finally:
+        codetracer.flush()
+        codetracer.stop()
+
+    parsed = _parse_trace(out_dir)
+    names = [f["name"] for f in parsed.functions]
+    assert any(name == "<my_pkg.mod>" for name in names), f"missing module name in {names}"
+
+
 def test_all_argument_kinds_recorded_on_py_start(tmp_path: Path) -> None:
     # Arrange: write a script with a function using all Python argument kinds
     code = (

design-docs/module-call-event-naming-implementation-plan.status.md

@@ -23,13 +23,13 @@
 
 ### WS2 – Runtime Tracer Integration
 - **Scope recap:** Detect module-level code (`co_qualname == "<module>"`) and rename call events to `<module-name>` using the shared resolver; plumb filter-derived names to avoid duplicate work.
-- **Status:** _In Progress_
-- **Notes:** `RuntimeTracer` now owns a `ModuleIdentityCache`, rewrites module-level function names via shared hints, clears the cache between runs, and has a regression test (`module_import_records_module_name`) confirming `<my_pkg.mod>` call records. Remaining work: thread globals-based hints (if needed) and add higher-level integration tests / documentation (see WS3).
+- **Status:** _Completed_
+- **Notes:** `RuntimeTracer` now rewrites module-level call events via `ModuleIdentityCache`, clears the cache alongside `function_ids`, and exposes a test hook to verify naming logic. Added a unit test (`module_import_records_module_name`) and a Python integration test (`test_module_imports_record_package_names`) that traces a real import to confirm `<pkg.mod>` shows up in `trace.json`.
 
 ### WS3 – Testing, Tooling, and Docs
 - **Scope recap:** Add regression tests (Python + Rust) validating the new naming, update documentation/changelog, and refresh any snapshot expectations.
-- **Status:** _Not Started_
-- **Notes:** Tests will likely live in `tests/python/test_monitoring_events.py` and a dedicated Rust module; docs update TBD.
+- **Status:** _In Progress_
+- **Notes:** New Rust + Python tests cover module-name derivation; README now documents the `<pkg.module>` behaviour. Remaining work: update changelog/other docs if required once feature is finalized.
 
 ## Next Checkpoints
 1. Implement shared resolver scaffolding (WS1).