WS4-WS5

codetracer-python-recorder/src/runtime/tracer/events.rs: 
codetracer-python-recorder/src/runtime/tracer/lifecycle.rs: 
codetracer-python-recorder/src/runtime/tracer/runtime_tracer.rs: 
codetracer-python-recorder/tests/python/test_exit_payloads.py: 
codetracer-python-recorder/tests/python/test_trace_balance.py: 
design-docs/toplevel-exit-and-trace-gating-implementation-plan.status.md: 

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

Author: tzanko-matev

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

@@ -454,9 +454,12 @@ impl Tracer for RuntimeTracer {
 
         self.emit_session_exit(py);
 
+        let exit_summary = self.exit_summary();
+
         if self.lifecycle.encountered_failure() {
             if policy.keep_partial_trace {
-                if let Err(err) = self.lifecycle.finalise(&mut self.writer, &self.filter) {
+                if let Err(err) = self.lifecycle.finalise(&mut self.writer, &self.filter, &exit_summary)
+                {
                     with_error_code(ErrorCode::TraceIncomplete, || {
                         log::warn!(
                             "failed to finalise partial trace after disable: {}",
@@ -489,7 +492,7 @@ impl Tracer for RuntimeTracer {
             .require_trace_or_fail(&policy)
             .map_err(ffi::map_recorder_error)?;
         self.lifecycle
-            .finalise(&mut self.writer, &self.filter)
+            .finalise(&mut self.writer, &self.filter, &exit_summary)
             .map_err(ffi::map_recorder_error)?;
         self.function_ids.clear();
         self.module_names.clear();

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

@@ -6,6 +6,8 @@ use crate::runtime::activation::ActivationController;
 use crate::runtime::io_capture::ScopedMuteIoCapture;
 use crate::runtime::output_paths::TraceOutputPaths;
 use crate::runtime::tracer::filtering::FilterCoordinator;
+use crate::runtime::tracer::runtime_tracer::ExitSummary;
+use log::debug;
 use recorder_errors::{enverr, usage, ErrorCode, RecorderResult};
 use runtime_tracing::{NonStreamingTraceWriter, TraceWriter};
 use serde_json::{self, json};
@@ -105,12 +107,12 @@ impl LifecycleController {
         &mut self,
         writer: &mut NonStreamingTraceWriter,
         filter: &FilterCoordinator,
+        exit_summary: &ExitSummary,
     ) -> RecorderResult<()> {
         TraceWriter::finish_writing_trace_metadata(writer).map_err(|err| {
             enverr!(ErrorCode::Io, "failed to finalise trace metadata")
                 .with_context("source", err.to_string())
         })?;
-        self.append_filter_metadata(filter)?;
         TraceWriter::finish_writing_trace_paths(writer).map_err(|err| {
             enverr!(ErrorCode::Io, "failed to finalise trace paths")
                 .with_context("source", err.to_string())
@@ -119,6 +121,9 @@ impl LifecycleController {
             enverr!(ErrorCode::Io, "failed to finalise trace events")
                 .with_context("source", err.to_string())
         })?;
+        debug!("[Lifecycle] writing exit metadata: code={:?}, label={:?}", exit_summary.code, exit_summary.label);
+        self.append_filter_metadata(filter)?;
+        self.append_exit_metadata(exit_summary)?;
         Ok(())
     }
 
@@ -132,6 +137,49 @@ impl LifecycleController {
         self.encountered_failure = false;
     }
 
+    fn append_exit_metadata(&self, exit_summary: &ExitSummary) -> RecorderResult<()> {
+        let Some(outputs) = &self.output_paths else {
+            return Ok(());
+        };
+
+        let path = outputs.metadata();
+        let original = fs::read_to_string(path).map_err(|err| {
+            enverr!(ErrorCode::Io, "failed to read trace metadata")
+                .with_context("path", path.display().to_string())
+                .with_context("source", err.to_string())
+        })?;
+
+        let mut metadata: serde_json::Value = serde_json::from_str(&original).map_err(|err| {
+            enverr!(ErrorCode::Io, "failed to parse trace metadata JSON")
+                .with_context("path", path.display().to_string())
+                .with_context("source", err.to_string())
+        })?;
+
+        if let serde_json::Value::Object(ref mut obj) = metadata {
+            let status = json!({
+                "code": exit_summary.code,
+                "label": exit_summary.label,
+            });
+            obj.insert("process_exit_status".to_string(), status);
+            let serialised = serde_json::to_string(&metadata).map_err(|err| {
+                enverr!(ErrorCode::Io, "failed to serialise trace metadata")
+                    .with_context("path", path.display().to_string())
+                    .with_context("source", err.to_string())
+            })?;
+            fs::write(path, serialised).map_err(|err| {
+                enverr!(ErrorCode::Io, "failed to write trace metadata")
+                    .with_context("path", path.display().to_string())
+                    .with_context("source", err.to_string())
+            })?;
+            Ok(())
+        } else {
+            Err(
+                enverr!(ErrorCode::Io, "trace metadata must be a JSON object")
+                    .with_context("path", path.display().to_string()),
+            )
+        }
+    }
+
     fn append_filter_metadata(&self, filter: &FilterCoordinator) -> RecorderResult<()> {
         let Some(outputs) = &self.output_paths else {
             return Ok(());

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

@@ -28,6 +28,12 @@ enum ExitPayload {
     Text(Cow<'static, str>),
 }
 
+#[derive(Clone, Debug, Default)]
+pub(crate) struct ExitSummary {
+    pub code: Option<i32>,
+    pub label: Option<String>,
+}
+
 impl ExitPayload {
     fn is_code(&self) -> bool {
         matches!(self, ExitPayload::Code(_))
@@ -94,6 +100,19 @@ impl SessionExitState {
     fn is_emitted(&self) -> bool {
         self.emitted
     }
+
+    fn summary(&self) -> ExitSummary {
+        match &self.payload {
+            ExitPayload::Code(value) => ExitSummary {
+                code: Some(*value),
+                label: None,
+            },
+            ExitPayload::Text(text) => ExitSummary {
+                code: None,
+                label: Some(text.as_ref().to_string()),
+            },
+        }
+    }
 }
 
 /// Minimal runtime tracer that maps Python sys.monitoring events to
@@ -202,6 +221,10 @@ impl RuntimeTracer {
         self.session_exit.set_exit_code(exit_code);
     }
 
+    pub(super) fn exit_summary(&self) -> ExitSummary {
+        self.session_exit.summary()
+    }
+
     pub(super) fn evaluate_gate(
         &mut self,
         py: Python<'_>,

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

@@ -49,6 +49,10 @@ def test_cli_records_exit_code_in_toplevel_return(tmp_path: Path) -> None:
     assert exit_value["kind"] == "Int"
     assert exit_value["i"] == 3
 
+    metadata = json.loads((trace_dir / "trace_metadata.json").read_text(encoding="utf-8"))
+    status = metadata.get("process_exit_status")
+    assert status == {"code": 3, "label": None}
+
 
 def test_default_exit_payload_uses_placeholder(tmp_path: Path) -> None:
     trace_dir = tmp_path / "trace"
@@ -68,3 +72,7 @@ def test_default_exit_payload_uses_placeholder(tmp_path: Path) -> None:
     exit_value = _last_return_value(trace_dir)
     assert exit_value["kind"] == "String"
     assert exit_value["text"] == "<exit>"
+
+    metadata = json.loads((trace_dir / "trace_metadata.json").read_text(encoding="utf-8"))
+    status = metadata.get("process_exit_status")
+    assert status == {"code": None, "label": "<exit>"}

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

@@ -1,10 +1,13 @@
 import json
 import importlib.util
+import runpy
 from pathlib import Path
 from typing import List, Mapping
 
 import pytest
 
+import codetracer_python_recorder as codetracer
+
 from codetracer_python_recorder.trace_balance import (
     TraceBalanceError,
     TraceBalanceResult,
@@ -99,3 +102,79 @@ def test_cli_reports_success_for_balanced_trace(tmp_path: Path, capsys: pytest.C
 
     assert exit_code == 0
     assert "Balanced trace" in captured.out
+
+
+def test_activation_and_filter_skip_still_balances_trace(tmp_path: Path) -> None:
+    script = tmp_path / "app.py"
+    script.write_text(
+        """
+def side_effect():
+    for _ in range(3):
+        pass
+
+if __name__ == "__main__":
+    side_effect()
+""",
+        encoding="utf-8",
+    )
+
+    filter_file = tmp_path / "skip.toml"
+    filter_file.write_text(
+        """
+[meta]
+name = "skip-main"
+version = 1
+
+[scope]
+default_exec = "trace"
+default_value_action = "allow"
+
+[[scope.rules]]
+selector = "pkg:__main__"
+exec = "skip"
+value_default = "allow"
+""",
+        encoding="utf-8",
+    )
+
+    trace_dir = tmp_path / "trace"
+
+    session = codetracer.start(
+        trace_dir,
+        format="json",
+        start_on_enter=script,
+        trace_filter=[filter_file],
+    )
+    try:
+        runpy.run_path(str(script), run_name="__main__")
+    finally:
+        session.stop()
+
+    events = load_trace_events(trace_dir / "trace.json")
+    function_names: dict[int, str] = {}
+    next_function_id = 0
+    for event in events:
+        payload = event.get("Function")
+        if payload:
+            function_names[next_function_id] = payload.get("name", "")
+            next_function_id += 1
+
+    toplevel_ids = {fid for fid, name in function_names.items() if name == "<toplevel>"}
+    assert len(toplevel_ids) == 1, f"expected single toplevel function, saw {toplevel_ids}"
+
+    toplevel_call_count = sum(
+        1
+        for event in events
+        if "Call" in event and event["Call"].get("function_id") in toplevel_ids
+    )
+    assert toplevel_call_count == 1
+
+    exit_returns = [
+        event["Return"]
+        for event in events
+        if "Return" in event and event["Return"].get("return_value", {}).get("text") == "<exit>"
+    ]
+    assert len(exit_returns) == 1
+
+    script_names = {name for name in function_names.values() if name not in {"<toplevel>"}}
+    assert "side_effect" not in script_names

design-docs/toplevel-exit-and-trace-gating-implementation-plan.status.md

@@ -34,10 +34,16 @@
   - Verification: `just cargo-test` and `just py-test`.
 
 ### WS4 – Lifecycle & Metadata Updates
-- **Status:** _Not Started_.
+- **Status:** _Completed_
+  - Metadata writer now records `process_exit_status` alongside filter info, and runtime emits a `<toplevel>` return before finalisation.
+  - Added regression coverage in Python for both exit code and default placeholder metadata values.
+  - Verification: `just cargo-test`, `just py-test`.
 
 ### WS5 – Validation & Parity Follow-Up
-- **Status:** _Not Started_.
+- **Status:** _Completed_
+- Added explicit tests verifying exit metadata plus activation/filter interplay keeps the trace balanced (`test_exit_payloads`, `test_trace_balance`).
+- Documented follow-up to mirror exit-status support in the pure-Python recorder before release.
+- Verification: `just cargo-test`, `just py-test`.
 
 ## Notes
 - API changes will require a minor version bump once runtime support lands; capture release planning tasks after WS2.