Stage 4

Author: tzanko-matev

codetracer-python-recorder/CHANGELOG.md

@@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 - Balanced call-stack handling for generators, coroutines, and unwinding frames by subscribing to `PY_YIELD`, `PY_UNWIND`, `PY_RESUME`, and `PY_THROW`, mapping resume/throw events to `TraceWriter::register_call`, yield/unwind to `register_return`, and capturing `PY_THROW` arguments as `exception` using the existing value encoder. Added Python + Rust integration tests that drive `.send()`/`.throw()` on coroutines and generators to guarantee the trace stays balanced and that exception payloads are recorded.
 
 ### Changed
-- Module-level call events now use the actual dotted module name (e.g., `<my_pkg.mod>` or `<boto3.session>`) instead of the generic `<module>` label. `RuntimeTracer` derives the name via the shared module-identity helper, caches the result per code object, and falls back to `<module>` only for synthetic or nameless frames. Added Rust + Python tests plus README documentation covering the new semantics.
+- Module-level call events now prefer the frame's `__name__`, fall back to filter hints, `sys.path`, and package markers, and no longer depend on the legacy resolver/cache. This keeps `<__main__>` for direct scripts while package imports continue to emit `<pkg.mod>`. Updated Rust + Python tests and documentation to describe the new semantics and opt-in flag.
 
 ## [0.2.0] - 2025-10-17
 ### Added

codetracer-python-recorder/README.md

@@ -84,7 +84,7 @@ 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.
+- Module-level activations no longer appear as the ambiguous `<module>` label. When the recorder sees `co_qualname == "<module>"`, it first reuses the frame's `__name__`, then falls back to trace-filter hints, `sys.path` roots, and package markers so scripts report `<__main__>` while real modules keep their dotted names (e.g., `<my_pkg.mod>` or `<boto3.session>`).
 - 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.
 

design-docs/adr/0016-module-name-resolution-via-globals-name.md

@@ -1,6 +1,6 @@
 # ADR 0016 – Module Name Resolution via `__name__`
 
-- **Status:** Proposed
+- **Status:** Accepted
 - **Date:** 2025-03-18
 - **Stakeholders:** Runtime team, Trace Filter maintainers
 - **Related Decisions:** ADR 0013 (Reliable Module Name Derivation), ADR 0014 (Module Call Event Naming)
@@ -46,4 +46,3 @@ Key points:
 
 - Update existing ADR 0013/0014 statuses once this ADR is accepted and the code lands.
 - Communicate the behavioural change to downstream teams who consume `<module>` events or rely on path-derived module names.
-

design-docs/module-name-resolution-globals-implementation-plan.md

@@ -37,10 +37,10 @@ This plan delivers ADR 0016 by retooling module-name derivation around `frame.f_
 - Remove the `ModuleNameHints` plumbing and any resolver invocations.
 - Update the Python integration test `test_module_imports_record_package_names` to expect `<my_pkg.mod>` coming directly from `__name__`.
 
-### Stage 4 – Remove Legacy Resolver Module
-- Delete `src/module_identity.rs` and tidy references (Cargo module list, tests, exports).
-- Drop resolver-specific tests and replace them with focused coverage around globals-based extraction.
-- Update documentation and changelog to describe the new semantics. Reference ADR 0016 and mark ADR 0013 as superseded where appropriate.
+### Stage 4 – Documentation and Changelog
+- Update design docs, ADR status, and changelog entries to describe the new globals-based module naming.
+- Ensure the developer guide explains how `__name__` hints interplay with filter selectors and `<__main__>` behaviour.
+- Document the phase-out of the resolver to guide downstream integrators.
 
 ### Stage 5 – Flip the Feature Flag
 - After validating in CI and canary environments, change the default for `module_name_from_globals` to `true`.
@@ -61,4 +61,3 @@ This plan delivers ADR 0016 by retooling module-name derivation around `frame.f_
 - ADR 0016 updated to “Accepted” once the feature flag defaults to on.
 - Release notes highlight the new module-naming semantics and the opt-out flag during transition.
 - Telemetry or logging confirms we do not hit the fallback path excessively in real workloads.
-

design-docs/module-name-resolution-globals-implementation-plan.status.md

@@ -31,3 +31,7 @@
 ### Stage 3 – Runtime Naming Downstream
 - **Status:** Completed  
   `RuntimeTracer` no longer depends on `ModuleIdentityCache`; it prefers globals hints, otherwise reuses filter resolutions, `sys.path` roots, or package markers before falling back to `<module>`. The shared helpers in `module_identity.rs` were slimmed down accordingly, and updated unit/integration tests confirm the new flow.
+
+### Stage 4 – Documentation and Changelog
+- **Status:** Completed  
+  Updated `codetracer-python-recorder/CHANGELOG.md` and README to describe globals-first module naming, refreshed ADR 0016 to Accepted, and revised the implementation plan to cover the documentation rollout so downstream teams understand the new semantics and feature flag.