# `PtcRunner.Kernel.Capability`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/capability.ex#L1)

A host-owned route from PTC-Lisp to trusted extension code.

`name` is the environment-local Lisp tool name. `input_schema` is the frozen
bounded JSON Schema checked before the optional semantic `validate` callback,
budget reservation, and provider invocation. `output_schema`, when present,
checks successful values before they return to Lisp. `callback` returns
`{:ok, json_value}` or `{:error, %PtcRunner.Kernel.ProviderError{}}`.
Expected transient failures must use `ProviderError` with an explicit
`retryable?: true`. The dispatcher contains callback raises, exits, throws,
and monitored process deaths, but these unclassified failures default to
non-retryable.
One-argument callbacks receive only normalized arguments. Trusted
two-argument callbacks additionally receive a dispatcher-owned invocation
context for private observation and safe trace propagation; that context
never crosses into Lisp.

`description` supplies bounded discovery metadata. `model_visible` controls
prompt inventory only; every installed callable capability remains available
to runtime documentation. Neither field grants authority. A capability can be
invoked only when the host placed it in the active workflow or mission
environment.

Callbacks and validators remain host-owned and are never projected into Lisp
values. The dispatcher contains ordinary raises, exits, timeouts, and
oversized or invalid results, but capability implementations are trusted
BEAM extensions rather than an adversarial-code boundary.

# `callback`

```elixir
@type callback() ::
  (map() -&gt; callback_result())
  | (map(), invocation_context() -&gt; callback_result())
```

# `callback_result`

```elixir
@type callback_result() ::
  {:ok, term()} | {:error, PtcRunner.Kernel.ProviderError.t()}
```

# `invocation_context`

```elixir
@type invocation_context() :: %{
  capability_id: binary(),
  inspection_sink: PtcRunner.Kernel.InspectionSink.t() | nil,
  traceparent: binary() | nil
}
```

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.Capability{
  callback: callback(),
  description: binary() | nil,
  effect: :read | :write | :unknown,
  input_schema: map(),
  input_validator: PtcRunner.Kernel.JSONSchema.compiled(),
  inspection_capture: :full | :digest_results,
  llm_reservation: map() | nil,
  model_visible: boolean(),
  name: binary(),
  output_schema: map() | nil,
  output_validator: PtcRunner.Kernel.JSONSchema.compiled() | nil,
  validate: (map() -&gt; :ok | {:error, binary()}) | nil
}
```

# `metadata`

```elixir
@spec metadata(t()) :: map()
```

Returns sanitized discovery metadata without the callback or validator.

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, :invalid_capability}
```

Constructs a capability from required `:name`, `:callback`, and
`:input_schema` options plus optional `:output_schema`, `:effect`,
`:validate`, `:description`, `:model_visible`, `:inspection_capture`, and
`:llm_reservation` options.

Names are bounded lower-case identifiers and may contain `.`, `_`, `/`, and
`-`. Descriptions are limited to 4,096 bytes. Schemas use the bounded JSON
Schema 2020-12 profile compiled by `PtcRunner.Kernel.JSONSchema`. Input
property and constrained-literal keys must already use their underscore form
so recursive Lisp argument normalization cannot change their meaning.
Effects are `:read`, `:write`, or `:unknown` and default to `:unknown`.
`:inspection_capture` is `:full` (the default) or `:digest_results`;
`:digest_results` requires `effect: :read` and directs private inspection to
retain a deterministic value identity in place of a successful result. It is
private capture policy and never appears in `metadata/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
