PtcRunner.Kernel.TraceLog (PtcRunner v0.15.0)

Copy Markdown View Source

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 source/0 variant.

Summary

Types

source()
t()

Functions

append_jsonl(path, events, opts \\ [])

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(opts)

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(trace_log, operation, arguments)

Executes one validated, source-scoped bounded trace query.

Types

source()

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

t()

@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
}

Functions

append_jsonl(path, events, opts \\ [])

@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(opts)

@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(trace_log, operation, arguments)

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

Executes one validated, source-scoped bounded trace query.