traceact 0.6.2__tar.gz → 0.8.1__tar.gz

{traceact-0.6.2/traceact.egg-info → traceact-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.2
+Version: 0.8.1
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -55,6 +55,7 @@ pip install traceact
 from traceact import traced_action, configure, TraceConfig, JsonlSink
 
 configure(
+    project="my-app",
     config=TraceConfig(sink_mode="blocking"),
     sinks=[JsonlSink("data/traces.jsonl")],
 )

{traceact-0.6.2 → traceact-0.8.1}/README.md

@@ -20,6 +20,7 @@ pip install traceact
 from traceact import traced_action, configure, TraceConfig, JsonlSink
 
 configure(
+    project="my-app",
     config=TraceConfig(sink_mode="blocking"),
     sinks=[JsonlSink("data/traces.jsonl")],
 )

{traceact-0.6.2 → traceact-0.8.1}/USAGE.md

@@ -94,6 +94,7 @@ Call `configure()` once at application startup before any traces run.
 from traceact import configure, TraceConfig, TraceBudget, JsonlSink, ConsoleSink
 
 configure(
+    project="my-app",           # stamps every trace; viewer uses this as the source name
     config=TraceConfig(
         enabled=True,
         sink_mode="blocking",   # "blocking" | "buffered" | "disabled"
@@ -119,6 +120,8 @@ configure(
 
 All fields are optional. Omitted fields use package defaults. `configure()` can be called multiple times; later calls replace earlier ones.
 
+**`project`** is the recommended way to name your traces. It is stamped onto every trace produced by this process and used by the viewer to label the source. Traces written without a `project` emit a `UserWarning` at runtime. A per-trace `project=` argument on `@traced_action` or `ActionTrace.start()` overrides the package-level value for that trace only.
+
 **Sink modes:**
 - `"blocking"` — write immediately when a trace finishes. Best for development.
 - `"buffered"` — hold traces in memory, flush on exit or on explicit `flush_buffer()`. Best for production.
@@ -1356,7 +1359,7 @@ The Terminal window stays open so Ctrl+C stops the viewer. To pass a source file
 
 - **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, correlation ID, or touched target, against the currently tailed rows. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view. A pre-filtered view opened via `TraceLog.view()` instead searches the full source on disk — see [Server-side search](#server-side-search-apiquery) below.
 - **Trace inspector** — selecting a trace shows its own ID, its parent and root trace IDs (when it is a child trace), correlation ID (when present, shown in full), kind, duration, and touch/error counts. "Copy JSON" copies the full record.
-- **Trace map** — a visual of one trace: the action as origin, its events and resources as connected nodes, with per-node status and a red marker on failures. Plays as a sequential step-through replay, with a speed slider (1×–10×, live, persisted) and pause/play.
+- **Trace map** — a visual of one trace: the action as origin, its events and resources as connected nodes, with per-node status and a red marker on failures. Plays as a sequential step-through replay, with a speed slider (1×–10×, live, persisted) and pause/play. The map zooms and pans: the mouse wheel zooms about the cursor, left-drag pans, and the `+` / `−` / `⟲` buttons zoom about the centre and reset to 1×. Zoom is clamped to 0.2×–5× and resets when you select a different trace.
 - **Settings** — accent colour, display density, default trace view, row count, default replay speed, and a **Run diagnostics** button — all persisted to `localStorage` except diagnostics, which runs fresh each time.
 
 ### Run diagnostics (Settings)
@@ -1447,9 +1450,32 @@ launch_or_connect(
     port=8765,        # port to try if starting a new viewer
     open_browser=False,
     timeout=3.0,      # seconds to wait for a freshly started server to be ready
-) -> str              # returns the viewer URL, e.g. "http://127.0.0.1:8765/"
+    name=None,        # label for this source in the picker; derived from the path if unset
+) -> str              # returns the viewer URL, e.g. "http://127.0.0.1:8765/?source=agora"
 ```
 
+### How sources are named
+
+The viewer labels each source in its picker. Left to itself it derives the name from the path, skipping components that describe storage rather than a project (`traces`, `data`, `logs`, `output`, `var`, `tmp`, and similar):
+
+| Path | Name |
+|---|---|
+| `~/Dev/agora/data/traces/traces.jsonl` | `agora` |
+| `~/Dev/casewright/logs/traces.jsonl` | `casewright` |
+| `~/Dev/agora/agora_traces.jsonl` | `agora_traces` |
+| `~/Dev/agora/data/traces/worker.jsonl` | `worker` |
+| `~/Dev/agora/data/traces/traces.1234.jsonl` | `agora` |
+
+A filename that already identifies the project is used as-is, so an app that writes `agora_traces.jsonl` keeps that name. Only a generic filename falls through to the directory walk. Per-process shards and rotated segments reduce to the same project name, so they don't fill the picker with near-identical entries.
+
+Pass `name` when the app knows its own identity and shouldn't depend on where its files sit:
+
+```python
+launch_or_connect(source="data/traces/traces.jsonl", name="agora")
+```
+
+Sources are deduplicated by resolved path, so calling `launch_or_connect()` on every run reuses the existing entry rather than adding `agora-2`, `agora-3`, … Two different paths that derive the same name still get a numeric suffix to stay distinguishable.
+
 ### Frontend button
 
 The button should be a `<button>` (not an `<a href>`), so you can disable it and show a loading state while the backend starts the viewer:

{traceact-0.6.2 → traceact-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.6.2"
+version = "0.8.1"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"

traceact-0.8.1/tests/test_project_name.py

@@ -0,0 +1,153 @@
+# tests/test_project_name.py
+#
+# Tests for configure(project=...), project cascading to traces, and the
+# warning emitted when a root trace is written without a project name.
+
+import warnings
+
+import pytest
+
+import traceact
+from traceact import ActionTrace, configure, reset_config
+from traceact.config import get_package_project
+from traceact.trace import _create_trace
+
+
+# ---------------------------------------------------------------------------
+# configure(project=...) — package-level state
+# ---------------------------------------------------------------------------
+
+class TestConfigureProject:
+    def test_project_stored_in_package_state(self):
+        configure(project="agora")
+        assert get_package_project() == "agora"
+
+    def test_reset_clears_project(self):
+        configure(project="agora")
+        reset_config()
+        assert get_package_project() is None
+
+    def test_configure_without_project_does_not_clear_existing(self):
+        configure(project="agora")
+        configure()  # no project arg
+        assert get_package_project() == "agora"
+
+    def test_configure_project_can_be_updated(self):
+        configure(project="alpha")
+        configure(project="beta")
+        assert get_package_project() == "beta"
+
+
+# ---------------------------------------------------------------------------
+# Project cascading — package → trace
+# ---------------------------------------------------------------------------
+
+class TestProjectCascade:
+    def test_package_project_stamped_onto_trace(self, tmp_path):
+        configure(project="agora")
+        with ActionTrace.start(action="test.run") as trace:
+            pass
+        assert trace.project == "agora"
+
+    def test_per_trace_project_overrides_package(self, tmp_path):
+        configure(project="agora")
+        with ActionTrace.start(action="test.run", project="override") as trace:
+            pass
+        assert trace.project == "override"
+
+    def test_child_inherits_package_project(self):
+        configure(project="agora")
+        with ActionTrace.start(action="parent") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "agora"
+
+    def test_child_inherits_parent_project_when_package_unset(self):
+        with ActionTrace.start(action="parent", project="manual") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "manual"
+
+    def test_package_project_wins_over_parent_project(self):
+        # Package is the top of the cascade — it overrides even an explicit
+        # parent project so that configure(project=...) is a single source of
+        # truth for the whole app.
+        configure(project="package-level")
+        with ActionTrace.start(action="parent", project="parent-level") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "package-level"
+
+    def test_no_project_anywhere_leaves_none(self):
+        with ActionTrace.start(action="test.run") as trace:
+            pass
+        assert trace.project is None
+
+    def test_project_appears_in_serialised_record(self, tmp_path):
+        import json
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(
+            project="agora",
+            config=traceact.TraceConfig(sink_mode="blocking"),
+            sinks=[traceact.JsonlSink(str(f))],
+        )
+        with ActionTrace.start(action="test.run"):
+            pass
+        records = [json.loads(l) for l in f.read_text().splitlines() if l.strip()]
+        assert records[-1]["project"] == "agora"
+
+
+# ---------------------------------------------------------------------------
+# Warning on unnamed root traces
+# ---------------------------------------------------------------------------
+
+class TestUnnamedTraceWarning:
+    def test_warns_when_no_project_set(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert any("project" in m for m in msgs)
+
+    def test_no_warning_when_project_set_via_configure(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(project="agora", sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert not any("project" in m for m in msgs)
+
+    def test_no_warning_when_project_set_per_trace(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run", project="agora"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert not any("project" in m for m in msgs)
+
+    def test_child_trace_does_not_warn(self, tmp_path):
+        # Only root traces warn — spamming for every child would be noise.
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="parent"):
+                with ActionTrace.start(action="child"):
+                    pass
+        project_warnings = [
+            w for w in caught
+            if issubclass(w.category, UserWarning) and "project" in str(w.message)
+        ]
+        # At most one warning (the root), never two.
+        assert len(project_warnings) <= 1

{traceact-0.6.2 → traceact-0.8.1}/tests/test_viewer_instance.py

@@ -12,7 +12,72 @@ import unittest.mock as mock
 
 import pytest
 
-from traceact.viewer.server import ViewerState
+from traceact.viewer.server import ViewerState, _derive_name
+
+
+# ---------------------------------------------------------------------------
+# Source naming
+# ---------------------------------------------------------------------------
+#
+# Nearly every app writes to some variant of <project>/data/traces/traces.jsonl,
+# so a name taken from the filename alone reads "traces" for every project on
+# the machine. These assert the name identifies the project instead.
+
+class TestDeriveName:
+    def test_skips_generic_dirs_to_project_name(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces/traces.jsonl") == "agora"
+
+    def test_skips_logs_dir(self):
+        assert _derive_name("/Users/mo/Dev/casewright/logs/traces.jsonl") == "casewright"
+
+    def test_two_projects_get_different_names(self):
+        # The whole point: same filename, same layout, different projects.
+        a = _derive_name("/Users/mo/Dev/agora/data/traces/traces.jsonl")
+        b = _derive_name("/Users/mo/Dev/casewright/data/traces/traces.jsonl")
+        assert a != b
+
+    def test_specific_filename_is_honoured(self):
+        # An app that already names its file per project keeps that name —
+        # the directory walk is only a fallback for generic filenames.
+        assert _derive_name("/Users/mo/Dev/agora/agora_traces.jsonl") == "agora_traces"
+
+    def test_non_generic_filename_wins_over_dir(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces/worker.jsonl") == "worker"
+
+    def test_hidden_project_dir_loses_leading_dot(self):
+        assert _derive_name("/Users/mo/.tree/traces/traces.jsonl") == "tree"
+
+    def test_pid_shard_derives_project_not_shard(self):
+        # All shards of one project must derive the same name, or a sharded
+        # app fills the picker with near-identical entries.
+        a = _derive_name("/Users/mo/Dev/agora/data/traces/traces.1234.jsonl")
+        b = _derive_name("/Users/mo/Dev/agora/data/traces/traces.5678.jsonl")
+        assert a == b == "agora"
+
+    def test_rotated_segment_derives_project(self):
+        path = "/Users/mo/Dev/agora/data/traces/traces.20260726T120000000000Z.jsonl"
+        assert _derive_name(path) == "agora"
+
+    def test_folder_source_skips_generic_components(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces") == "agora"
+
+    def test_all_generic_falls_back(self):
+        assert _derive_name("/data/traces/traces.jsonl") == "source"
+
+    def test_generic_matching_is_case_insensitive(self):
+        assert _derive_name("/Users/mo/Dev/agora/Data/Traces/Traces.jsonl") == "agora"
+
+    def test_traceact_state_dir_is_generic(self):
+        assert _derive_name("/Users/mo/.traceact/imports/dropped.jsonl") == "dropped"
+
+    def test_bare_filename_does_not_crash(self):
+        assert _derive_name("traces.jsonl") == "source"
+
+    def test_explicit_name_overrides_derivation(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        assert state.add_source(str(f), name="agora") == "agora"
 
 
 # ---------------------------------------------------------------------------
@@ -32,12 +97,15 @@ class TestAddSourceDedupe:
     def test_repeated_adds_do_not_accumulate(self, tmp_path):
         # The reported symptom: an app calling launch_or_connect() on every
         # run produced traces-2, traces-3, traces-4 ... for one unchanging file.
+        # Asserts the dedupe property, not the derived name — the name comes
+        # from the tmp directory here and is covered by TestDeriveName.
         f = tmp_path / "traces.jsonl"
         f.write_text("")
         state = ViewerState()
         for _ in range(5):
             state.add_source(str(f))
-        assert list(state.sources) == ["traces"]
+        assert len(state.sources) == 1
+        assert not any(n.endswith("-2") for n in state.sources)
 
     def test_relative_and_absolute_path_dedupe(self, tmp_path, monkeypatch):
         f = tmp_path / "traces.jsonl"
@@ -129,6 +197,58 @@ class TestLaunchOrConnectSourcePin:
             url = instance.launch_or_connect()
         assert url == "http://127.0.0.1:8765/"
 
+    def test_explicit_name_forwarded_to_add_source(self):
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ), mock.patch.object(
+            instance, "add_source_to",
+            return_value={"name": "agora", "path": "/x/traces.jsonl"},
+        ) as add:
+            url = instance.launch_or_connect(source="/x/traces.jsonl", name="agora")
+        assert add.call_args.kwargs["name"] == "agora"
+        assert url == "http://127.0.0.1:8765/?source=agora"
+
+    def test_add_source_to_omits_name_when_not_given(self):
+        # The payload must not carry name=None; the server treats a missing
+        # name as "derive one" and an explicit null would be a different case.
+        from traceact.viewer import instance
+
+        captured = {}
+
+        class FakeResp:
+            def __enter__(self): return self
+            def __exit__(self, *a): return False
+            def read(self): return b'{"name":"x","path":"/x"}'
+
+        def fake_urlopen(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp()
+
+        with mock.patch("urllib.request.urlopen", side_effect=fake_urlopen):
+            instance.add_source_to("127.0.0.1", 8765, "/x/traces.jsonl")
+        assert captured["body"] == {"path": "/x/traces.jsonl"}
+
+    def test_add_source_to_includes_name_when_given(self):
+        from traceact.viewer import instance
+
+        captured = {}
+
+        class FakeResp:
+            def __enter__(self): return self
+            def __exit__(self, *a): return False
+            def read(self): return b'{"name":"agora","path":"/x"}'
+
+        def fake_urlopen(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp()
+
+        with mock.patch("urllib.request.urlopen", side_effect=fake_urlopen):
+            instance.add_source_to("127.0.0.1", 8765, "/x/traces.jsonl", name="agora")
+        assert captured["body"]["name"] == "agora"
+
     def test_failed_add_falls_back_to_bare_url(self):
         # add_source_to returns None when the running viewer can't be reached;
         # a URL pinning a source that was never registered would be worse than
@@ -255,3 +375,87 @@ class TestPrivateInstanceStateGating:
         rc, _, clear_state = self._run_view(["view", "--no-browser"], monkeypatch)
         assert rc == 0
         assert clear_state.called
+
+
+# ---------------------------------------------------------------------------
+# Project-field-based source naming
+# ---------------------------------------------------------------------------
+#
+# When a source contains trace records with a non-null project field, the
+# viewer uses that value as the source name rather than deriving it from the
+# file path. This keeps the name stable even if the file is moved, and works
+# identically for JSONL, SQLite, and future HTTP sources.
+
+import json as _json  # already imported above, but named alias avoids shadowing
+
+
+class TestProjectFieldNaming:
+    def _write_traces(self, path, records):
+        with open(path, "w", encoding="utf-8") as fh:
+            for r in records:
+                fh.write(_json.dumps(r) + "\n")
+
+    def test_project_field_used_as_source_name(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert name == "agora"
+
+    def test_project_name_marked_as_named(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert state.source_named[name] is True
+
+    def test_path_derived_name_marked_as_unnamed(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert state.source_named[name] is False
+
+    def test_empty_source_falls_back_to_path(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        # Empty file has no project — must not crash and must produce a name.
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert name  # non-empty
+
+    def test_null_project_falls_back_to_path(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": None, "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        # null project is treated the same as absent — path derivation runs.
+        assert state.source_named[name] is False
+
+    def test_explicit_name_param_beats_project_field(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f), name="override")
+        assert name == "override"
+        assert state.source_named[name] is True
+
+    def test_directory_source_reads_project_from_first_file(self, tmp_path):
+        (tmp_path / "a.jsonl").write_text(
+            _json.dumps({"project": "myapp", "action": "x"}) + "\n"
+        )
+        state = ViewerState()
+        name = state.add_source(str(tmp_path))
+        assert name == "myapp"
+        assert state.source_named[name] is True
+
+    def test_collision_suffix_applied_to_project_name(self, tmp_path):
+        f1 = tmp_path / "a.jsonl"
+        f2 = tmp_path / "b.jsonl"
+        self._write_traces(f1, [{"project": "agora"}])
+        self._write_traces(f2, [{"project": "agora"}])
+        state = ViewerState()
+        n1 = state.add_source(str(f1))
+        n2 = state.add_source(str(f2))
+        assert n1 == "agora"
+        assert n2 == "agora-2"

{traceact-0.6.2 → traceact-0.8.1}/traceact/__init__.py

@@ -70,7 +70,7 @@
 #   TraceActASGIMiddleware — ASGI middleware (FastAPI, Starlette). Same as
 #                   above for async frameworks.
 
-__version__ = "0.6.2"
+__version__ = "0.8.1"
 
 from traceact.config import configure, reset_config, TraceConfig
 from traceact.budget import TraceBudget

{traceact-0.6.2 → traceact-0.8.1}/traceact/config.py

@@ -149,12 +149,14 @@ class TraceConfig:
 _package_config: Optional[TraceConfig] = None
 _package_budget: Any = None          # Optional[TraceBudget] — typed as Any to avoid circular import
 _package_sinks: List[Any] = []       # List[Sink]
+_package_project: Optional[str] = None  # set via configure(project=...); stamped onto every trace
 
 
 def configure(
     config: Optional[TraceConfig] = None,
     budget: Any = None,
     sinks: Optional[List[Any]] = None,
+    project: Optional[str] = None,
 ) -> None:
     """
     Set package-wide defaults for all future traces.
@@ -163,20 +165,25 @@ def configure(
     baseline for every trace unless a specific trace or decorator overrides them.
 
     Args:
-        config:  A TraceConfig instance. Only non-None fields are applied; the
-                 rest keep their current values (or package defaults).
-        budget:  A TraceBudget instance. Only non-None fields are applied.
-        sinks:   A list of sink objects (JsonlSink, ConsoleSink, etc.). Replaces
-                 the current sink list entirely.
+        config:   A TraceConfig instance. Only non-None fields are applied; the
+                  rest keep their current values (or package defaults).
+        budget:   A TraceBudget instance. Only non-None fields are applied.
+        sinks:    A list of sink objects (JsonlSink, ConsoleSink, etc.). Replaces
+                  the current sink list entirely.
+        project:  The application or project name. Stamped onto every trace so
+                  the viewer can label sources by their project rather than by
+                  the sink's file path. Required in practice — traces written
+                  without a project name emit a warning.
 
     Example:
         configure(
+            project="my-app",
             config=TraceConfig(enabled=True, sink_mode="buffered"),
             budget=TraceBudget(max_events=200),
             sinks=[JsonlSink("traces.jsonl")],
         )
     """
-    global _package_config, _package_budget, _package_sinks
+    global _package_config, _package_budget, _package_sinks, _package_project
 
     if config is not None:
         _package_config = config
@@ -187,6 +194,9 @@ def configure(
     if sinks is not None:
         _package_sinks = list(sinks)
 
+    if project is not None:
+        _package_project = project
+
 
 def reset_config() -> None:
     """
@@ -207,11 +217,18 @@ def reset_config() -> None:
         - Traces that have already been written to a sink. Those are gone.
         - Files on disk. JsonlSink output is not deleted.
     """
-    global _package_config, _package_budget, _package_sinks
+    global _package_config, _package_budget, _package_sinks, _package_project
 
     _package_config = None
     _package_budget = None
     _package_sinks = []
+    _package_project = None
+
+    # Discard any buffered records so one test's buffered traces cannot leak
+    # into the next test's buffer state. Imported here to avoid a circular
+    # import at module load time (sinks.py does not import config.py).
+    from traceact.sinks import reset_buffer
+    reset_buffer()
 
     # Clear the active trace context so tests start with a clean slate.
     # The deferred import avoids a circular dependency at module load time
@@ -244,3 +261,8 @@ def get_package_budget() -> Any:
 def get_package_sinks() -> List[Any]:
     """Return the current list of configured sinks."""
     return _package_sinks
+
+
+def get_package_project() -> Optional[str]:
+    """Return the package-level project name, or None if not set."""
+    return _package_project

{traceact-0.6.2 → traceact-0.8.1}/traceact/sinks.py

@@ -76,6 +76,21 @@ def _ensure_flush_registered() -> None:
         _flush_registered = True
 
 
+def reset_buffer() -> None:
+    """
+    Discard all buffered records and reset the atexit flush registration.
+
+    Call this in test teardown (via reset_config()) to prevent one test's
+    buffered traces from leaking into the next test's buffer state. Not
+    intended for production use — buffered records not yet flushed to a sink
+    are silently discarded.
+    """
+    global _flush_registered
+    with _buffer_lock:
+        _buffer.clear()
+    _flush_registered = False
+
+
 def buffer_record(record: Dict[str, Any]) -> None:
     """
     Add a finished trace record to the in-memory buffer.

{traceact-0.6.2 → traceact-0.8.1}/traceact/trace.py

@@ -40,10 +40,13 @@ from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Union
 
 from traceact.budget import BUDGET_DEFAULTS, TraceBudget
+import warnings
+
 from traceact.config import (
     TraceConfig,
     get_package_budget,
     get_package_config,
+    get_package_project,
     get_package_sinks,
 )
 from traceact.context import SKIP, get_active_trace, is_skip, pop_trace, push_trace
@@ -1047,6 +1050,17 @@ class ActionTrace(TraceHelpersMixin):
         if mode == "disabled":
             return
 
+        # Warn once when a root trace (no parent) is about to be written with no
+        # project set. Child traces are silent — the root already told them.
+        if self.project is None and self.parent_trace_id is None:
+            warnings.warn(
+                "TraceAct: trace written without a project name. "
+                "Add project='your-app' to your configure() call so the viewer "
+                "can label this source correctly.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         sinks = get_package_sinks()
 
         # If no sinks have been configured, fall back to ConsoleSink so that
@@ -1231,11 +1245,18 @@ def _create_trace(
         return _NoOpTrace()
 
     # --- Create the real trace ---
+    # If the caller didn't specify a project, inherit from the package config,
+    # then from the parent trace. Package wins over parent so that a single
+    # configure(project=...) stamps every trace regardless of nesting depth.
+    resolved_project = project or get_package_project() or (
+        parent.project if parent is not None else None
+    )
+
     trace = ActionTrace(
         action=action,
         kind=kind,
         actor=actor,
-        project=project,
+        project=resolved_project,
         parent=parent,
         correlation_id=correlation_id,
         upstream_trace_id=upstream_trace_id,