PtcRunner.Kernel.InspectionSnapshot (PtcRunner v0.14.0)

Copy Markdown View Source

Owner-bound immutable capture of private inspection artifacts.

A snapshot inventories one bounded directory, loads each regular .inspection.jsonl artifact exactly once through InspectionArtifact, and validates every artifact against an already captured TraceSnapshot. Duplicate runs, orphaned identities, malformed artifacts, output-only capability joins, incomplete MCP joins, replacement during capture, and aggregate or retained limits fail the entire capture. Validated input-only capability attempts remain available as explicitly incomplete records. MCP request/response pairs are retained atomically so interruption cannot publish only half of an exchange. No partial catalog is published.

The owner process holds only compiled query collections and safe metadata. Paths and private records are redacted from process status. Its tokenized handle is opaque and capabilities retain only that handle.

Summary

Types

retained_limit_error()
t()
trace_snapshot()

Opaque handle to the canonical trace snapshot this capture is correlated with.

unsupported_schema_error()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

info(snapshot)
query(snapshot, operation, arguments)
start(source, trace_snapshot, opts \\ [])
stop(snapshot)

Types

retained_limit_error()

@type retained_limit_error() ::
  {:source_retained_limit_exceeded,
   %{
     source: :ptc_inspection_snapshot,
     measured_bytes: pos_integer(),
     limit_bytes: pos_integer()
   }}

t()

@opaque t()

trace_snapshot()

@type trace_snapshot() :: term()

Opaque handle to the canonical trace snapshot this capture is correlated with.

Declared locally so the public inspection API does not borrow a type from the internal trace-snapshot implementation.

unsupported_schema_error()

@type unsupported_schema_error() ::
  PtcRunner.Kernel.InspectionArtifact.unsupported_schema_error()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

info(snapshot)

@spec info(t()) :: {:ok, map()} | {:error, atom()}

query(snapshot, operation, arguments)

@spec query(t(), PtcRunner.Kernel.InspectionQuery.operation(), map()) ::
  {:ok, map()} | {:error, atom()}

start(source, trace_snapshot, opts \\ [])

@spec start({:directory, binary()}, trace_snapshot(), keyword()) ::
  {:ok, t()}
  | {:error, atom() | retained_limit_error() | unsupported_schema_error()}

stop(snapshot)

@spec stop(term()) :: :ok