Milestone 5 - Step 6

codetracer-python-recorder/src/runtime/mod.rs: 
codetracer-python-recorder/src/runtime/tracer/io.rs: 
codetracer-python-recorder/src/runtime/tracer/mod.rs: 
design-docs/adr/0001-file-level-single-responsibility.md: 
design-docs/codetracer-architecture-refactor-implementation-plan.status.md: 
design-docs/file-level-srp-refactor-plan.md: 
design-docs/value-capture.md: 

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

Author: tzanko-matev

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

@@ -1,4 +1,7 @@
-//! Runtime tracer facade translating sys.monitoring callbacks into `runtime_tracing` records.
+//! Runtime tracing facade wiring sys.monitoring callbacks into dedicated collaborators.
+//!
+//! The [`tracer`] module hosts lifecycle, IO, filtering, and event pipelines and re-exports
+//! [`RuntimeTracer`] so callers can keep importing it from `crate::runtime`.
 
 mod activation;
 mod frame_inspector;
@@ -10,7 +13,5 @@ pub mod tracer;
 mod value_capture;
 mod value_encoder;
 
-#[allow(unused_imports)]
-pub use line_snapshots::{FrameId, LineSnapshotStore};
 pub use output_paths::TraceOutputPaths;
 pub use tracer::RuntimeTracer;

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

@@ -15,33 +15,37 @@ use std::sync::Arc;
 use std::thread::ThreadId;
 
 /// Coordinates installation, flushing, and teardown of the IO capture pipeline.
-pub struct IoCoordinator {
+pub(crate) struct IoCoordinator {
     snapshots: Arc<LineSnapshotStore>,
     pipeline: Option<IoCapturePipeline>,
 }
 
 impl IoCoordinator {
     /// Create a coordinator with a fresh snapshot store and no active pipeline.
-    pub fn new() -> Self {
+    pub(crate) fn new() -> Self {
         Self {
             snapshots: Arc::new(LineSnapshotStore::new()),
             pipeline: None,
         }
     }
 
     /// Expose the shared snapshot store for collaborators (tests, IO capture).
-    pub fn snapshot_store(&self) -> Arc<LineSnapshotStore> {
+    pub(crate) fn snapshot_store(&self) -> Arc<LineSnapshotStore> {
         Arc::clone(&self.snapshots)
     }
 
     /// Install the IO capture pipeline using the provided settings.
-    pub fn install(&mut self, py: Python<'_>, settings: IoCaptureSettings) -> PyResult<()> {
+    pub(crate) fn install(
+        &mut self,
+        py: Python<'_>,
+        settings: IoCaptureSettings,
+    ) -> PyResult<()> {
         self.pipeline = IoCapturePipeline::install(py, Arc::clone(&self.snapshots), settings)?;
         Ok(())
     }
 
     /// Flush buffered output for the active thread before emitting a step event.
-    pub fn flush_before_step(
+    pub(crate) fn flush_before_step(
         &self,
         thread_id: ThreadId,
         writer: &mut NonStreamingTraceWriter,
@@ -55,7 +59,7 @@ impl IoCoordinator {
     }
 
     /// Flush every buffered chunk regardless of thread affinity.
-    pub fn flush_all(&self, writer: &mut NonStreamingTraceWriter) -> bool {
+    pub(crate) fn flush_all(&self, writer: &mut NonStreamingTraceWriter) -> bool {
         let Some(pipeline) = self.pipeline.as_ref() else {
             return false;
         };
@@ -65,7 +69,11 @@ impl IoCoordinator {
     }
 
     /// Drain remaining chunks and uninstall the capture pipeline.
-    pub fn teardown(&mut self, py: Python<'_>, writer: &mut NonStreamingTraceWriter) -> bool {
+    pub(crate) fn teardown(
+        &mut self,
+        py: Python<'_>,
+        writer: &mut NonStreamingTraceWriter,
+    ) -> bool {
         let Some(mut pipeline) = self.pipeline.take() else {
             return false;
         };
@@ -87,12 +95,12 @@ impl IoCoordinator {
     }
 
     /// Clear the snapshot cache once tracing concludes.
-    pub fn clear_snapshots(&self) {
+    pub(crate) fn clear_snapshots(&self) {
         self.snapshots.clear();
     }
 
     /// Record the latest frame snapshot for the active thread.
-    pub fn record_snapshot(
+    pub(crate) fn record_snapshot(
         &self,
         thread_id: ThreadId,
         path_id: PathId,
@@ -192,7 +200,7 @@ impl IoCoordinator {
 }
 
 /// Translate chunk flags into telemetry labels.
-pub fn flag_labels(flags: IoChunkFlags) -> Vec<&'static str> {
+fn flag_labels(flags: IoChunkFlags) -> Vec<&'static str> {
     let mut labels = Vec::new();
     if flags.contains(IoChunkFlags::NEWLINE_TERMINATED) {
         labels.push("newline");

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

@@ -1,4 +1,6 @@
 //! Collaborators for the runtime tracer lifecycle, IO coordination, filtering, and event handling.
+//!
+//! Re-exports [`RuntimeTracer`] so downstream callers continue using `crate::runtime::RuntimeTracer`.
 
 pub mod events;
 pub mod filtering;

design-docs/adr/0001-file-level-single-responsibility.md

@@ -9,7 +9,7 @@
 
 The codetracer Python recorder crate has evolved quickly and several source files now mix unrelated concerns:
 - [`src/lib.rs`](../../codetracer-python-recorder/src/lib.rs) hosts PyO3 module wiring, global logging setup, tracing session state, and filesystem validation in one place.
-- [`src/runtime_tracer.rs`](../../codetracer-python-recorder/src/runtime_tracer.rs) interleaves activation gating, writer lifecycle control, PyFrame helpers, and Python value encoding logic, making it challenging to test or extend any portion independently.
+- [`src/runtime/tracer/runtime_tracer.rs`](../../codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs) (formerly `src/runtime_tracer.rs`) interleaves activation gating, writer lifecycle control, PyFrame helpers, and Python value encoding logic, making it challenging to test or extend any portion independently.
 - [`src/tracer.rs`](../../codetracer-python-recorder/src/tracer.rs) combines sys.monitoring shim code with the `Tracer` trait, callback registration, and global caches.
 - [`codetracer_python_recorder/api.py`](../../codetracer-python-recorder/codetracer_python_recorder/api.py) mixes format constants, backend interaction, context manager ergonomics, and environment based auto-start side effects.
 
@@ -43,7 +43,7 @@ These changes are mechanical reorganisations—no behavioural changes are expect
 2. **Preserve APIs.** When moving functions, re-export them from their new module so that existing callers (Rust and Python) compile without modification in the same PR.
 3. **Add Focused Tests.** Whenever a helper is extracted (e.g., value encoding), add or migrate unit tests that cover its edge cases.
 4. **Document Moves.** Update doc comments and module-level docs to reflect the new structure. Remove outdated TODOs or convert them into follow-up issues.
-5. **Coordinate on Shared Types.** When splitting `runtime_tracer.rs`, agree on ownership for shared structs (e.g., `RuntimeTracer` remains in `runtime/mod.rs`). Use `pub(crate)` to keep internals encapsulated.
+5. **Coordinate on Shared Types.** When evolving the `runtime::tracer` modules, agree on ownership for shared structs (e.g., `RuntimeTracer` remains re-exported from `runtime/mod.rs`). Use `pub(crate)` to keep internals encapsulated.
 6. **Python Imports.** After splitting the Python modules, ensure `__all__` in `__init__.py` continues to export the public API. Use relative imports to avoid accidental circular dependencies.
 7. **Parallel Work.** Follow the sequencing from `design-docs/file-level-srp-refactor-plan.md` to know when tasks can proceed in parallel.
 

design-docs/codetracer-architecture-refactor-implementation-plan.status.md

@@ -84,6 +84,7 @@
 - ✅ Milestone 5 Step 3: introduced `runtime::tracer::filtering::FilterCoordinator` to own scope resolution, skip caching, telemetry stats, and metadata wiring. `RuntimeTracer` now delegates trace decisions and summary emission, while tests continue to validate skip behaviour and metadata shape with unchanged expectations.
 - ✅ Milestone 5 Step 4: carved lifecycle orchestration into `runtime::tracer::lifecycle::LifecycleController`, covering activation gating, writer initialisation/finalisation, policy enforcement, failure cleanup, and trace id scoping. Added focused unit tests for the controller and re-ran `just test` (nextest + pytest) to verify no behavioural drift.
 - ✅ Milestone 5 Step 5: shifted event handling into `runtime::tracer::events`, relocating the `Tracer` trait implementation alongside failure-injection helpers and telemetry wiring. `RuntimeTracer` now exposes a slim collaborator API (`mark_event`, `flush_io_before_step`, `ensure_function_id`), while tests import the trait explicitly. `just test` (nextest + pytest) confirms the callbacks behave identically after the split.
+- ✅ Milestone 5 Step 6: harmonised the tracer module facade by tightening `IoCoordinator` visibility, pruning unused re-exports, documenting the `runtime::tracer` layout, and updating design docs that referenced the legacy `runtime_tracer.rs` path. `just test` (Rust nextest + Python pytest) verified the cleanup.
 
 
 ### Planned Extraction Order (Milestone 4)
@@ -114,5 +115,5 @@
 5. **Tests:** After each move, update unit tests in `trace_filter` modules and dependent integration tests (`session/bootstrap.rs` tests, `runtime` tests). Targeted command: `just test` (covers Rust + Python suites).
 
 ## Next Actions
-1. Kick off Milestone 5 Step 6 by harmonising the new tracer submodules (facade re-exports, docs, dead code sweep) ahead of integration cleanup.
+1. Scope the Milestone 6 integration/cleanup tasks (CI configs, packaging metadata, doc updates) now that the runtime tracer refactor is complete.
 2. Track stakeholder feedback and spin out follow-up issues if new risks surface.

design-docs/file-level-srp-refactor-plan.md

@@ -7,7 +7,7 @@
 
 ## Current State Observations
 - `src/lib.rs` is responsible for PyO3 module registration, lifecycle management for tracing sessions, global logging initialisation, and runtime format selection, which mixes unrelated concerns in one file.
-- `src/runtime_tracer.rs` couples trace lifecycle control, activation toggling, and Python value encoding in a single module, making it difficult to unit test or substitute individual pieces.
+- `src/runtime/tracer/runtime_tracer.rs` (previously the monolithic `runtime_tracer.rs`) couples trace lifecycle control, activation toggling, and Python value encoding in a single module, making it difficult to unit test or substitute individual pieces.
 - `src/tracer.rs` combines the `Tracer` trait definition, sys.monitoring shims, callback registration utilities, and thread-safe storage, meaning small changes can ripple through unrelated logic.
 - `codetracer_python_recorder/api.py` interleaves environment based auto-start, context-manager ergonomics, backend state management, and format constants, leaving no clearly isolated entry-point for CLI or library callers.
 

design-docs/value-capture.md

@@ -336,7 +336,7 @@ result = builtins_test([5, 3, 7])
 # General Rules
 
 * This spec is for `/codetracer-python-recorder` project and NOT for `/codetracer-pure-python-recorder`
-* Code and tests should be added to `/codetracer-python-recorder/src/runtime_tracer.rs`
+* Code and tests should be added under `/codetracer-python-recorder/src/runtime/tracer/` (primarily `runtime_tracer.rs` and its collaborators)
 * Performance is important. Avoid using Python modules and functions and prefer PyO3 methods including the FFI API.
 * If you want to run Python do it like so `uv run python` This will set up the right venv. Similarly for running tests `uv run pytest`.
 * After every code change you need to run `just dev` to make sure that you are testing the new code. Otherwise some tests might run against the old code