PtcRunner.Kernel.AnalysisSessionBuilder (PtcRunner v0.14.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-run-analysis-v1 requires one authorized private destination before either source is captured, alongside physical separation of its 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()
unsupported_schema_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()
   }}

unsupported_schema_error()

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

Functions

start(profile_id, resources, destination)

@spec start(binary(), resources(), destination()) ::
  {:ok, PtcRunner.Kernel.AnalysisSession.t(), map()}
  | {:error, atom() | retained_limit_error() | unsupported_schema_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.