PtcRunner.Kernel.CommandDiagnostic (PtcRunner v0.14.0)

Copy Markdown View Source

Closed privacy-safe command diagnostic.

Construction accepts only a catalog pair, a catalog-authorized message, and typed safe provenance. Contract-authorized paths must also match the sealed contract authority bound to their source classification. Rendering never inspects a lower-level reason or rejected value. Catalog-authorized dynamic message shapes contain only fixed literals plus bounded PTC-Lisp symbol names, sealed provider-selection field names, a catalog-validated runtime ceiling, a bounded agent turn ceiling, an opaque replay request hash, or a closed component-override field rule. Compile messages require component-source provenance; a missing capability message is rebuilt from the frozen bundle's sorted tool requirements. A missing MCP tool message may retain only the validated, declaration-owned upstream name and carries no provider catalog payload. Kernel runtime and replay messages require fixed runtime provenance. An agent turn-limit message and an out-of-range agent option have no source because max_turns and the other bounded options belong to one agent.core call rather than a host or manifest document. A provider-selection message names sealed rule fields and a closed rule; it has no source because the provider subject already locates the slot. Every other message is the catalog literal.

notes is reserved and always empty: the published V3 envelope schema pins it to {"const": []}, so a populated array would invalidate the envelope for every strict V3 consumer. Reporting a rejected value against the bound it broke is a later-version change, not a producer-side one.

Summary

Types

span()

@type span() :: %{start_byte: non_neg_integer(), end_byte: non_neg_integer()} | nil

t()

@type t() :: %PtcRunner.Kernel.CommandDiagnostic{
  code: atom(),
  exit_status: 2 | 3 | 4 | 5 | 6 | 7 | 70,
  message: binary(),
  notes: [],
  path: PtcRunner.Kernel.CommandPath.t() | nil,
  phase: PtcRunner.Kernel.DiagnosticCatalog.phase(),
  provider_activity: boolean(),
  retryable: boolean(),
  source: PtcRunner.Kernel.CommandSource.t() | nil,
  span: span(),
  subject: PtcRunner.Kernel.CommandSubject.t() | nil
}

Functions

new(phase, code, opts \\ [])

@spec new(PtcRunner.Kernel.DiagnosticCatalog.phase(), atom(), keyword()) ::
  {:ok, t()} | {:error, :invalid_command_diagnostic}

new!(phase, code, opts \\ [])

to_map(diagnostic)

@spec to_map(t()) :: map()

valid?(diagnostic)

@spec valid?(term()) :: boolean()