traceact 0.5.0__tar.gz → 0.6.0__tar.gz

{traceact-0.5.0/traceact.egg-info → traceact-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.5.0
+Version: 0.6.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -128,7 +128,7 @@ Double-click `launch.command` in the repo root to open TraceAct from Finder with
 
 The source modal (click the source name in the header) lets you:
 
-- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Choose file / Choose folder** — opens a native macOS picker; returns the filesystem path for live tailing
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 

{traceact-0.5.0 → traceact-0.6.0}/README.md

@@ -93,7 +93,7 @@ Double-click `launch.command` in the repo root to open TraceAct from Finder with
 
 The source modal (click the source name in the header) lets you:
 
-- **Choose file / Choose folder** — opens a native macOS picker; returns the real filesystem path for live tailing
+- **Choose file / Choose folder** — opens a native macOS picker; returns the filesystem path for live tailing
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 

{traceact-0.5.0 → traceact-0.6.0}/USAGE.md

@@ -626,7 +626,7 @@ configure(config=TraceConfig(redaction_presets=["filesystem_paths", "env_vars"])
 
 An unknown preset name raises `ValueError` immediately at `TraceConfig(...)` construction, not later at trace time.
 
-Also settable per-decorator, same as any other `TraceConfig` field — but note that a decorator-level `redaction_presets` **replaces** the package-level list rather than adding to it, exactly like `capture_inputs` does:
+Also settable per-decorator, same as any other `TraceConfig` field — but note that a decorator-level `redaction_presets` **replaces** the package-level list rather than adding to it, the same way `capture_inputs` does:
 
 ```python
 @traced_action(action="report.export", kind="app",
@@ -635,7 +635,7 @@ def export_report(...):
     ...
 ```
 
-**These are field-name patterns, not content scanning.** A value is redacted because of what its *key* is called, not what it contains. `trace.input({"path": "/Users/mo/secret"})` is redacted by the `filesystem_paths` preset; `trace.input({"location": "/Users/mo/secret"})` is not, because `"location"` doesn't match any active pattern. This mirrors the baseline mechanism exactly (same substring, case-insensitive matching) — it's simple and has no false-positive risk from scanning arbitrary string content, at the cost of missing secrets stored under an unexpected field name.
+**These are field-name patterns, not content scanning.** A value is redacted because of what its *key* is called, not what it contains. `trace.input({"path": "/Users/mo/secret"})` is redacted by the `filesystem_paths` preset; `trace.input({"location": "/Users/mo/secret"})` is not, because `"location"` doesn't match any active pattern. This mirrors the baseline mechanism (same substring, case-insensitive matching) — it's simple and has no false-positive risk from scanning arbitrary string content, at the cost of missing secrets stored under an unexpected field name.
 
 **Nested redaction example:**
 
@@ -705,7 +705,7 @@ configure(sinks=[
 ])
 ```
 
-**When to use it:** any time the inner sink is slow or remote — an HTTP collector, a database, or a high-latency filesystem. For local files on fast hardware, the overhead of `JsonlSink` alone is rarely worth wrapping.
+**When to use it:** any time the inner sink is slow or remote — an HTTP collector, a database, or a high-latency filesystem. For local files on fast hardware, `JsonlSink` alone rarely needs the extra wrapping.
 
 **Backpressure — and why drops are always observable:**
 
@@ -983,6 +983,32 @@ log.filter(status="failed").render_table(n=25)  # cap rows shown
 
 Each terminal call re-reads the JSONL file(s) — there is no caching, so you always get the current state of a live source.
 
+`last()`/`first()` are memory-bounded: they hold at most `n` matching records per file at once rather than collecting every match before truncating. A broad filter (or no filter at all) over a large source costs memory proportional to `n`, not to how much of the source matches.
+
+### query() — bounded result plus two completeness flags
+
+```python
+result = log.filter(status="failed").query(500)
+result["traces"]         # up to 500 matches, newest-first
+result["scan_capped"]    # True if max_lines_scanned stopped the scan early
+result["limit_reached"]  # True if more than 500 traces matched
+```
+
+Two separate reasons a result might not be every match that exists:
+
+- `scan_capped` — the scan itself gave up early, per `max_lines_scanned`.
+- `limit_reached` — the scan finished (or found enough to stop), but `n` (or more) results matched — there may be more beyond what's returned. This is true of `last(n)` too; `last()` just has nowhere to report it, since it returns a plain list. Note that `len(result["traces"]) == n` alone can't tell you this — a bounded scan returns at most `n` regardless of whether `n` or a hundred thousand traces matched, so `limit_reached` is tracked from a count taken during the scan, not inferred from the result's length afterward.
+
+Use `query()` instead of `last()` when the caller needs to distinguish those two situations — this is what the viewer's `/api/query` endpoint uses under the hood (see [Server-side search](#server-side-search-apiquery) above). `last()`/`first()` keep returning a plain list; `query()` is a separate method rather than a change to their return shape, so nothing about them breaks for existing callers.
+
+### max_lines_scanned — bounding scan time
+
+```python
+log = TraceLog("data/traces.jsonl", max_lines_scanned=200_000)
+```
+
+Caps how many lines a scan reads (matched or not) before giving up and returning whatever was found, setting `scan_capped=True` on the next `query()` call. Defaults to `None` — unbounded, the same behaviour as before this existed. Set it when reading a source you don't control the size of, or when a single call needs a predictable worst-case cost (an HTTP handler, for instance — see below).
+
 ### Using TraceLog in tests
 
 ```python
@@ -1305,7 +1331,7 @@ Pass `--new` to bypass this and force a second instance — useful when you want
 
 The "Add source" modal supports three ways to load a source:
 
-- **Choose file / Choose folder buttons** — opens a native macOS file or folder picker. The picker runs on the server side via AppleScript (`osascript`), so it returns the real filesystem path and the viewer can tail it live. (Falls back to a `tkinter` dialog on non-macOS platforms.)
+- **Choose file / Choose folder buttons** — opens a native macOS file or folder picker. The picker runs on the server side via AppleScript (`osascript`), so it returns the filesystem path and the viewer can tail it live. (Falls back to a `tkinter` dialog on non-macOS platforms.)
 - **Drag and drop** — drop a `.jsonl` file onto the drop zone. The browser reads the file contents and posts them to the server, which saves a copy to `~/.traceact/imports/` and adds it as a source. Because the server holds a copy (not the original), this is a **static snapshot** — new writes to the original file won't appear. The viewer labels imported sources accordingly.
 - **Type a path** — a collapsible text input for pasting or typing an absolute path. This gives live tailing just like the command-line argument.
 
@@ -1319,11 +1345,11 @@ The "Add source" modal supports three ways to load a source:
 4. Installs or upgrades `traceact` inside that venv.
 5. Runs `traceact view`, waits for the server to be ready, then opens the browser.
 
-The Terminal window stays open so Ctrl+C stops the viewer cleanly. To pass a source file at launch from a script: `open launch.command path/to/traces.jsonl`.
+The Terminal window stays open so Ctrl+C stops the viewer. To pass a source file at launch from a script: `open launch.command path/to/traces.jsonl`.
 
 ### What the viewer shows
 
-- **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. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view.
+- **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.
 - **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.
@@ -1345,11 +1371,29 @@ These endpoints are available while a viewer is running. Apps and scripts can ca
 | `GET` | `/api/pick?type=file\|folder` | — | `{"path":"...","cancelled":bool}` |
 | `POST` | `/api/import` | `{"name":"file.jsonl","content":"..."}` | `{"name":"...","path":"...","imported":true}` |
 | `GET` | `/api/stream?source=NAME&limit=N` | — | SSE stream: `snapshot` then `append` events |
+| `GET` | `/api/query?source=NAME&field[__op]=value&limit=N` | — | `{"traces":[...],"scan_capped":bool,"limit_reached":bool,"count":N}` |
 
 `/api/doctor`'s `status` is `"pass"`, `"fail"`, or `"info"`; `hint` is present only on `"fail"` checks. `ok` is `true` only if every `"pass"`/`"fail"` check passed — `"info"` checks (traceact's version, whether a viewer is running) never affect it.
 
 The SSE stream delivers one `snapshot` message (the last N traces as a JSON array) then `append` messages for each newly-written trace. A `": keepalive"` comment is sent every 0.5 s when nothing new arrives, to keep the connection alive through proxies.
 
+### Server-side search (`/api/query`)
+
+The trace log's search box and the row-limit setting both operate on the live-tailed buffer — whatever the last N traces happen to be. That's fine for the search box (a quick, instant, client-side filter over what's currently in view), but a `TraceLog.view()` pre-filter is a precise, deliberately-specified query — it needs to find its match regardless of whether that match is still inside the tail window. `/api/query` answers filters against the whole source on disk, via `TraceLog`, and the viewer routes pre-filters through it automatically. You don't need to call it directly for that to happen.
+
+```
+GET /api/query?source=traces&status=failed&action__contains=order&limit=200
+```
+
+- Every query param except `source` and `limit` is a filter field, in the same `field` / `field__contains` / `field__startswith` / `field__endswith` form as `TraceLog.filter()`. Multiple params are ANDed, same as chaining `.filter()` calls.
+- `__re` is not accepted here — it's rejected with `400`. `TraceLog.filter(field__re=...)` only makes sense when the pattern comes from trusted code; over HTTP it's arbitrary caller-supplied input, and a catastrophic-backtracking pattern could hang the request. Use `__re` directly against `TraceLog` in Python instead.
+- **`limit` is hard-capped at 1000 server-side.** Requesting `limit=5000` against a source with 3000 matches returns only the newest 1000 — but not silently: `count` in the response is the count *returned*, not the count that matched, and `limit_reached` (below) tells you whether more may exist.
+- The response carries two separate completeness flags, both `false` when the result is everything that matched:
+  - **`scan_capped`** — `true` if the scan hit its internal line-read ceiling before finishing reading the source.
+  - **`limit_reached`** — `true` if more traces matched than `limit` allowed back (including when a too-large requested `limit` was clamped to 1000). `count == limit` is not itself a safe signal that nothing more exists — a bounded scan always returns at most `limit` regardless of whether `limit` or a hundred thousand traces matched, so this comes from a count taken during the scan, not from inspecting the returned list's length afterward.
+
+  Either flag `true` means the same thing to a caller: this may not be every match. The viewer shows "results may be incomplete" next to the pre-filter badges when either is set, rather than presenting a partial result as if it were exhaustive.
+
 ### Notes
 
 - The viewer is a **local, single-node development tool**. It reads files on the machine it runs on. Exposing one machine's traces to another over the network (`traceact serve`) is planned for a later version.

{traceact-0.5.0 → traceact-0.6.0}/pyproject.toml

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

{traceact-0.5.0 → traceact-0.6.0}/tests/test_tracelog.py

@@ -285,6 +285,265 @@ class TestCount:
         assert TraceLog(str(f)).filter(status="failed").count() == 1
 
 
+# ---------------------------------------------------------------------------
+# Bounded reads: last()/first() memory-bounding correctness, query(), and
+# max_lines_scanned. These are adversarial by design — each test is built to
+# find the case where a bounded, per-file algorithm could plausibly diverge
+# from the old "collect everything, then sort and slice" result, rather than
+# just re-confirming the happy path already covered by TestLastFirst above.
+# ---------------------------------------------------------------------------
+
+class TestBoundedCorrectness:
+    """
+    _read_bounded() collects each file's own top-n candidates rather than every
+    match, on the argument that the true global top-n must be a subset of that.
+    These tests are built specifically to break that argument if it's wrong:
+    matches skewed heavily into one file, ties across files, and n falling on
+    exact file/match boundaries.
+    """
+
+    def test_matches_skewed_into_one_file_still_correct(self, tmp_path):
+        # File A holds the 5 newest matches; file B holds only old matches.
+        # A naive "per file, keep the first n seen" (rather than newest n)
+        # would get this wrong if it didn't account for scan order.
+        _write_jsonl(tmp_path / "a.jsonl", [
+            _trace(f"a{i}", started_at=f"2026-07-25T{10+i:02d}:00:00Z")
+            for i in range(5)
+        ])
+        _write_jsonl(tmp_path / "b.jsonl", [
+            _trace(f"b{i}", started_at=f"2026-07-25T0{i}:00:00Z")
+            for i in range(5)
+        ])
+        result = TraceLog(str(tmp_path)).last(3)
+        assert [t["action"] for t in result] == ["a4", "a3", "a2"]
+
+    def test_matches_interleaved_across_many_small_files(self, tmp_path):
+        # One match per file, timestamps interleaved out of filename order,
+        # so correctness can't come from accidentally reading files in a
+        # convenient order.
+        timestamps = ["03:00", "09:00", "01:00", "07:00", "05:00"]
+        for i, ts in enumerate(timestamps):
+            _write_jsonl(
+                tmp_path / f"shard{i}.jsonl",
+                [_trace(f"t{i}", started_at=f"2026-07-25T{ts}:00Z")]
+            )
+        result = TraceLog(str(tmp_path)).last(2)
+        assert [t["action"] for t in result] == ["t1", "t3"]  # 09:00, 07:00
+
+    def test_exact_boundary_n_equals_total_matches(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace("a", started_at="2026-07-25T08:00:00Z"),
+            _trace("b", started_at="2026-07-25T09:00:00Z"),
+        ])
+        result = TraceLog(str(f)).last(2)
+        assert len(result) == 2
+
+    def test_more_matches_per_file_than_n_still_bounded_correctly(self, tmp_path):
+        # 100 matches in one file, asking for the last 3 — exercises the
+        # maxlen-deque eviction path specifically, not just small inputs.
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(23)  # hours 00-22, valid HH range
+        ])
+        result = TraceLog(str(f)).last(3)
+        assert [t["action"] for t in result] == ["t22", "t21", "t20"]
+
+    def test_first_stops_early_but_result_still_correct(self, tmp_path):
+        # first() early-exits per file once n matches are found; verify the
+        # early exit doesn't skip a legitimately-older match placed later in
+        # write order across multiple files.
+        _write_jsonl(tmp_path / "a.jsonl", [
+            _trace(f"a{i}", started_at=f"2026-07-25T{10+i:02d}:00:00Z")
+            for i in range(5)
+        ])
+        _write_jsonl(tmp_path / "b.jsonl", [
+            _trace(f"b{i}", started_at=f"2026-07-25T0{i}:00:00Z")
+            for i in range(5)
+        ])
+        result = TraceLog(str(tmp_path)).first(3)
+        assert [t["action"] for t in result] == ["b0", "b1", "b2"]
+
+    def test_filter_applied_before_bounding(self, tmp_path):
+        # The ring buffer must hold n *matching* records, not just the last n
+        # lines regardless of the filter — otherwise a filtered .last(n) could
+        # come back short even though n matches genuinely exist further back.
+        f = tmp_path / "traces.jsonl"
+        records = []
+        for i in range(20):
+            records.append(_trace(
+                f"n{i}", status="completed",
+                started_at=f"2026-07-25T{i:02d}:00:00Z",
+            ))
+        # Only the last 2 lines are failures; everything else is noise after.
+        records.append(_trace("fail1", status="failed", started_at="2026-07-25T21:00:00Z"))
+        records.append(_trace("fail2", status="failed", started_at="2026-07-25T22:00:00Z"))
+        _write_jsonl(f, records)
+        result = TraceLog(str(f)).filter(status="failed").last(5)
+        assert [t["action"] for t in result] == ["fail2", "fail1"]
+
+    def test_zero_n_returns_empty(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a")])
+        assert TraceLog(str(f)).last(0) == []
+        assert TraceLog(str(f)).first(0) == []
+
+    def test_negative_n_returns_empty(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a")])
+        assert TraceLog(str(f)).last(-5) == []
+        assert TraceLog(str(f)).first(-5) == []
+
+
+class TestQuery:
+    def test_query_returns_dict_shape(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a")])
+        result = TraceLog(str(f)).query(10)
+        assert set(result.keys()) == {"traces", "scan_capped", "limit_reached"}
+
+    def test_query_uncapped_by_default(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a"), _trace("b")])
+        result = TraceLog(str(f)).query(10)
+        assert result["scan_capped"] is False
+        assert len(result["traces"]) == 2
+
+    def test_limit_reached_false_when_fewer_matches_than_n(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a"), _trace("b")])
+        result = TraceLog(str(f)).query(10)
+        assert result["limit_reached"] is False
+
+    def test_limit_reached_true_when_more_matches_than_n(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(15)
+        ])
+        result = TraceLog(str(f)).query(10)
+        assert result["limit_reached"] is True
+        assert len(result["traces"]) == 10
+
+    def test_limit_reached_false_when_exactly_n_matches(self, tmp_path):
+        # Exactly n matches exist — every one was found, none were cut off.
+        # This is the case limit_reached must NOT flag as "may be more",
+        # since there genuinely isn't more.
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(10)
+        ])
+        result = TraceLog(str(f)).query(10)
+        assert result["limit_reached"] is False
+        assert len(result["traces"]) == 10
+
+    def test_limit_reached_false_for_zero_n(self, tmp_path):
+        # n<=0 is a degenerate "give me nothing" request, not "the limit was
+        # reached" — there is no limit to have reached.
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace("a")])
+        result = TraceLog(str(f)).query(0)
+        assert result["limit_reached"] is False
+        assert result["traces"] == []
+
+    def test_limit_reached_independent_of_scan_capped(self, tmp_path):
+        # Both flags can be true at once for different reasons: the scan gave
+        # up early (scan_capped) AND still happened to find >= n matches
+        # before that point (limit_reached). Neither implies the other.
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(20)
+        ])
+        result = TraceLog(str(f), max_lines_scanned=5).query(3)
+        assert result["scan_capped"] is True
+        assert result["limit_reached"] is True
+
+    def test_query_newest_first(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace("old", started_at="2026-07-25T08:00:00Z"),
+            _trace("new", started_at="2026-07-25T09:00:00Z"),
+        ])
+        result = TraceLog(str(f)).query(10)
+        assert [t["action"] for t in result["traces"]] == ["new", "old"]
+
+    def test_query_respects_filters(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace("a", status="completed"),
+            _trace("b", status="failed"),
+        ])
+        result = TraceLog(str(f)).filter(status="failed").query(10)
+        assert len(result["traces"]) == 1
+        assert result["traces"][0]["action"] == "b"
+
+
+class TestMaxLinesScanned:
+    """
+    max_lines_scanned bounds worst-case scan time — the counterpart to n
+    bounding memory. Every line counts against the cap, matched or not,
+    because the cost being bounded is reading and parsing, not matching.
+    """
+
+    def test_default_is_uncapped(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace(f"t{i}") for i in range(50)])
+        result = TraceLog(str(f)).query(10)
+        assert result["scan_capped"] is False
+
+    def test_cap_below_file_size_sets_capped_flag(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(20)
+        ])
+        result = TraceLog(str(f), max_lines_scanned=5).query(10)
+        assert result["scan_capped"] is True
+
+    def test_cap_returns_partial_not_empty_results(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [
+            _trace(f"t{i}", started_at=f"2026-07-25T{i:02d}:00:00Z")
+            for i in range(20)
+        ])
+        result = TraceLog(str(f), max_lines_scanned=5).query(10)
+        assert len(result["traces"]) > 0
+
+    def test_cap_at_exactly_line_count_not_capped(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace(f"t{i}") for i in range(10)])
+        result = TraceLog(str(f), max_lines_scanned=10).query(10)
+        assert result["scan_capped"] is False
+
+    def test_malformed_lines_count_against_cap(self, tmp_path):
+        # The cost being bounded is reading/parsing, so garbage lines must
+        # count too — otherwise a file of mostly-noise could evade the cap
+        # entirely by never producing a "match" to count.
+        f = tmp_path / "traces.jsonl"
+        f.write_text("not json\n" * 10 + json.dumps(_trace("real")) + "\n")
+        result = TraceLog(str(f), max_lines_scanned=5).query(10)
+        assert result["scan_capped"] is True
+        assert result["traces"] == []  # the real trace is past the cap
+
+    def test_cap_stops_reading_further_files_in_folder_source(self, tmp_path):
+        _write_jsonl(tmp_path / "a.jsonl", [_trace(f"a{i}") for i in range(20)])
+        _write_jsonl(tmp_path / "b.jsonl", [_trace("b0")])
+        # Cap small enough to exhaust inside a.jsonl alone.
+        result = TraceLog(str(tmp_path), max_lines_scanned=3).query(10)
+        assert result["scan_capped"] is True
+        assert all(t["action"].startswith("a") for t in result["traces"])
+
+    def test_cap_propagates_through_filter_and_copy(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        _write_jsonl(f, [_trace(f"t{i}") for i in range(20)])
+        log = TraceLog(str(f), max_lines_scanned=5).filter(kind="app")
+        result = log.query(10)
+        assert result["scan_capped"] is True
+
+
 # ---------------------------------------------------------------------------
 # render_table()
 # ---------------------------------------------------------------------------