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. Loading validates the complete event envelope,
schema version, JSON-like data, run/trace identity, timestamps, and monotonic
sequence before deriving query results. Each run must begin with exactly one
run-started; it may remain open or end with exactly one final
run-stopped.
Supported query operations are:
:list_runs— bounded filtered run summaries, including the run-started sequence and component-override provenance;: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.
The internal trace-snapshot owner uses this module's canonical validation and
query execution against one immutable directory capture. A snapshot is
deliberately not another public source/0 variant.
Summary
Functions
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.
Constructs a query boundary from required :source and optional positive
:max_source_bytes and :max_result_bytes limits.
Executes one validated, source-scoped bounded trace query.
Types
@type source() :: PtcRunner.Kernel.EventSink.t() | {:file, binary()} | {:directory, binary()}
@type t() :: %PtcRunner.Kernel.TraceLog{ max_result_bytes: pos_integer(), max_source_bytes: pos_integer(), source: source(), source_kind: :sanitized | :private }
Functions
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.
Constructs a query boundary from required :source and optional positive
:max_source_bytes and :max_result_bytes limits.
@spec query(t(), :list_runs | :get_run | :list_turns | :counters, map()) :: {:ok, map()} | {:error, atom()}
Executes one validated, source-scoped bounded trace query.