PtcRunner.Kernel.AnalysisSessionBuilder (PtcRunner v0.15.0)

Copy Markdown View Source

Host boundary for closed local analysis profiles.

The builder resolves a profile ID through the closed registry, captures only its declared directory resources, creates fresh bounded owners, and starts one attested PtcRunner.Kernel.AnalysisSession. No caller can supply a profile module, component, capability set, mission data, label, limit, or sink policy.

Private profiles require one authorized private destination before either source is captured, alongside physical separation of their trace, inspection, and analysis-trace directories.

Exactly one of two destinations must be supplied. private_terminal: true additionally requires attached stdin and stdout. private_unattended: true authorizes the caller's own streams instead, for a host that has decided where private values go without a terminal.

The attached-terminal check is an accident guard, not access control. It prevents a private value from reaching a log or transcript by mistake; it cannot prevent a determined caller, because isatty cannot distinguish a human's terminal from a pseudo-terminal allocated by script(1), tmux, or ssh -t, and because a same-UID caller can already read the inspection artifact directly. private_unattended makes deliberate non-interactive use explicit and greppable instead of requiring that workaround. Tests and trusted embedding frontends may inject the detected state with terminal_attached:; ordinary callers omit it and use the real terminal.

Summary

Types

destination()
resources()
retained_limit_error()

Functions

start(profile_id, resources, destination)

Starts one fixed analysis profile over immutable source captures.

Types

destination()

@type destination() :: {:directory, binary()}

resources()

@type resources() :: %{required(binary()) => binary()}

retained_limit_error()

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

Functions

start(profile_id, resources, destination)

@spec start(binary(), resources(), destination()) ::
  {:ok, PtcRunner.Kernel.AnalysisSession.t(), map()}
  | {:error, atom() | retained_limit_error()}

Starts one fixed analysis profile over immutable source captures.

The destination directory receives one atomically published <analysis-id>.jsonl trace on close. The Viewer may place a normal log profile's source and destination together. The private inspection profile always requires all three physical directory lineages to be disjoint, including through symlinks and ancestor aliases.