# `PtcRunner.Kernel.TraceLog`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/trace_log.ex#L1)

Bounded canonical trace loading, validation, filtering, and pagination.

A source is an in-memory `PtcRunner.Kernel.EventSink`, one JSONL file, or a
directory of JSONL files. Explicit files validate one complete aggregate.
Immutable directory capture instead treats each
`<run-id>[.private].jsonl` member as one filename-bound run, proves the
selected namespace and bytes stable, and isolates a damaged connected
identity component without hiding disjoint healthy runs. Each admitted run
validates the complete event envelope, schema version, JSON-like data,
run/trace identity, timestamps, monotonic sequence, and lifecycle.

Supported query operations are:

- `:list_runs` — bounded filtered run summaries, including the run-started
  sequence and component-override provenance, ordered by newest start instant
  and then descending run ID;
- `:get_run` — one run summary by run ID;
- `:list_turns` — ordered evaluation/capability facts for one run;
- `:counters` — aggregate counters for filtered runs, including LLM usage by
  alias/revision and by safely published resolved model.

Pagination cursors are bound to the source and operation. Every source and
result has an aggregate encoded-and-retained byte ceiling. A requested page
limit is an upper bound; pagination returns the largest prefix that fits both
measurements. Normal directory sources exclude the reserved private filename
suffix; private files require an explicit source.
Internal immutable capture may use a private authority that admits both
normal and private trace files while retaining accurate per-run provenance.
Its `directory_admission_v1` identity commits to every selected raw name,
content digest, classification, admitted event, provenance claim, and full
isolation component, but excludes absolute paths, opposite-class names, and
advisory exclusion counts.

A direct directory query creates that admission transiently on every call
under the same entry, file, source, retained, and result ceilings as an
immutable snapshot. Consequently a direct cursor observes later selected
evidence as `:source_changed`, while a snapshot cursor stays bound to its
retained admission. Run-scoped queries distinguish a grant-visible isolated
claim as `:run_isolated` from an absent or out-of-grant run as `:not_found`.

The internal trace-snapshot owner uses this module's canonical validation and
query execution against one immutable directory capture or one exact selected
canonical file. A snapshot is
deliberately not another public `t:source/0` variant.

# `source`

```elixir
@type source() ::
  PtcRunner.Kernel.EventSink.t() | {:file, binary()} | {:directory, binary()}
```

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.TraceLog{
  max_directory_entries: pos_integer(),
  max_result_bytes: pos_integer(),
  max_retained_bytes: pos_integer(),
  max_source_bytes: pos_integer(),
  max_trace_files: pos_integer(),
  source: source(),
  source_kind: :sanitized | :private
}
```

# `append_jsonl`

```elixir
@spec append_jsonl(binary(), [map()], keyword()) :: :ok | {:error, atom()}
```

Appends canonical events to one admin-selected JSONL file under a total byte
cap. `private: true` requires safe parent ancestry and a mode-`0600` file,
owned by the current process authority or root, creating a missing file
privately before publication. The permission-checked descriptor is retained
through validation and append so pathname replacement cannot redirect private
bytes. One OS-released advisory lease keyed by the parent-directory/name
identity remains held across first-file creation. A nested device/inode lease
serializes hard-link aliases. The fixed path-then-inode acquisition order
applies across BEAM processes and separate local runtimes.

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, :invalid_trace_log}
```

Constructs a query boundary from required `:source` and optional positive
`:max_source_bytes` and `:max_result_bytes` limits. Directory sources also
accept `:max_retained_bytes`, `:max_directory_entries`, and
`:max_trace_files`; all five directory limits may be lowered but never raised
above the canonical directory-query ceilings.

# `query`

```elixir
@spec query(t(), :list_runs | :get_run | :list_turns | :counters, map()) ::
  {:ok, map()} | {:error, atom()}
```

Executes one validated, source-scoped bounded trace query.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
