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

Sealed, declarative metadata for one installed provider implementation.

Descriptors contain no executable callback, credential value, endpoint,
command, path, OAuth authority, store/context, grant, token manager, or principal. Phase
5 may therefore normalize selections and compute identity without consulting
an implementation or crossing the provider-activity boundary.

`local_preflight` is a trust declaration rather than a capability flag. Only a
shipped source may declare `:audited_local`, because that value permits phase
7 to run the callback behind it before provider activity is marked. A
`:custom` registration declares `:unverified` instead, and its check becomes
active work after the phase-8 marker.
Live LLM installations also seal `structured_output_mode`,
`usage_guarantees`, `reservation_tariff`, and `request_timeout_ms` here so acquisition can
reconstruct the same workflow route the prepare callback reports. Public
snapshots and `models` rows omit those fields.
`PtcRunner.Kernel.InstallationCatalog` completes the rule: an
`:audited_local` declaration also requires a host runtime binding. Both rules
bound what may be declared; neither attests where an admitted implementation
came from.

# `data_policy`

```elixir
@type data_policy() :: %{
  data_class: :normal | :private_inspection,
  accepts_data: [:normal | :private_inspection]
}
```

# `source`

```elixir
@type source() ::
  :mcp
  | :llm
  | :llm_replay
  | :ptc_trace_snapshot
  | :ptc_private_trace_snapshot
  | :ptc_inspection_snapshot
  | :custom
```

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.ProviderDescriptor{
  accepts_data: [:normal | :private_inspection],
  attestation: binary() | nil,
  authority_fingerprint: binary() | nil,
  authorization_mode: :none | :oauth,
  connectivity_mode: :none | :acquisition | :probe,
  credential_names: [binary()],
  data_class: :normal | :private_inspection,
  destinations: [:workflow | :mission],
  installation_revision: binary(),
  local_preflight: :none | :audited_local | :unverified,
  probe_effect: nil | :metadata | :completion,
  provides: [atom()],
  request_timeout_ms: pos_integer() | nil,
  requires: [atom()],
  reservation_tariff: %{currency: String.t(), id: binary()} | nil,
  selection_rules: PtcRunner.Kernel.SelectionRules.t(),
  selection_validation: :declarative | :active,
  source: source(),
  structured_output_mode: :json_schema | :json_object | :unsupported | nil,
  usage_guarantees: %{tokens: boolean(), cost_currency: String.t() | nil} | nil,
  workflow_llm?: boolean()
}
```

# `data_policy`

```elixir
@spec data_policy(t()) :: data_policy()
```

Projects the declared data policy a run-bound builder must honor.

Run-bound registries carry only this projection. A complete descriptor also
holds selection rules, which are bounded but large enough that copying them
into every provider worker would compete with the provider heap limit.

# `display_projection`

```elixir
@spec display_projection(t(), binary()) :: map()
```

Returns safe installed metadata suitable for `models` and contexts.

# `new`

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

Validates and seals one provider declaration.

# `public_projection`

```elixir
@spec public_projection(t(), binary(), map()) :: map()
```

Projects only selector-safe declaration identity for one occurrence.

# `valid?`

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

Checks the closed descriptor shape and construction seal.

---

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