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

The complete host-constructed configuration for one Kernel run.

A configuration is one-shot: terminal publication finalizes its event sink,
and a later `PtcRunner.Kernel.run/2` with the same value fails with
`:event_sink_error`. Build a fresh configuration and sink for every run.

The required fields are:

- `workflow_environment` — trusted outer workflow code and capabilities;
- `missions` — zero to sixteen confined subordinate environments;
- `input` — a JSON-like map exposed as the workflow evaluation context;
- `limits` — normalized positive runtime ceilings;
- `event_sink` — the bounded owner of canonical run events.

An event sink must be open and use these exact limits. A normal sink carries
the standard two-event measured terminal reserve, must leave room for the
assembled `run-started` event, and must have a payload ceiling large enough
for the bounded loss summary and the maximum complete Runner/REPL usage
projection. Private sinks reserve no lossy terminal slots but retain the same
terminal-payload check.

Construction derives and freezes an inventory for every mission from its
environment and the limits. Each contains both the authoritative versioned
structured inventory and a separately versioned compact model rendering,
each with distinct hashes and byte counts. Hosts cannot supply mutable
inventory text.

`provider_session` is the single owner-backed provider cleanup boundary.
Its optional absolute `run_deadline` is derived from that sealed session so
active preflight and later Kernel execution consume one budget rather than
anchoring independent durations.
Before callbacks can start, execution binds it to the Runner or REPL session
owner and to the run state whose provider tasks it tracks.
`connector_snapshots` and closed `provider_warnings` are bounded safe metadata
copied into `run-started`; neither field is visible to Lisp.

`result_contract` is an optional sealed, compiled application contract
exposed only through the reserved workflow validator used by `agent.main`.
Its optional `result_contract_source` is the portable logical document name
used only for an attested result-contract diagnostic. Final publication
enforcement remains the responsibility of `RunBuilder`.

`labels` is an optional closed safe-metadata map. Caller-defined identifier
fields become SHA-256 fingerprints and tags use finite enumerated values
before the map enters `run-started`.
`session_profile` is an optional closed profile ID and SHA-256 digest used by
server-owned interactive mission sessions; it grants no authority and is
copied only into safe `run-started` metadata.
Constructing a config validates shape, recorder readiness, and ownership
objects but performs no execution and grants no authority beyond the supplied
environments.

`inspect_only` is a compile-and-inspect session flag. When true, Kernel,
provider, and capability routes fail closed; public `PtcRunner.Lisp.run/2`
cannot set it. An environment assembled with `inspect_only: true` is
attested as such and is refused by an ordinary (non-inspect-only)
configuration.

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.RunConfig{
  claim_id: reference(),
  connector_snapshots: [map()],
  event_sink: PtcRunner.Kernel.EventSink.t(),
  event_sink_owner: pid(),
  input: map(),
  inspect_only: boolean(),
  inspection_sink: PtcRunner.Kernel.InspectionSink.t() | nil,
  inspection_sink_owner: pid() | nil,
  labels: map(),
  limits: PtcRunner.Kernel.Limits.t(),
  missions: %{
    required(binary()) =&gt; %{
      environment: PtcRunner.Kernel.MissionEnvironment.t(),
      inventory: term()
    }
  },
  phase_return_contracts: %{required(binary()) =&gt; map()},
  provider_session: PtcRunner.Kernel.ProviderSession.t() | nil,
  provider_warnings: [PtcRunner.Kernel.CommandWarning.t()],
  result_contract: PtcRunner.Kernel.ValueContract.t() | nil,
  result_contract_source: binary() | nil,
  result_projection: :native | :json,
  run_deadline: PtcRunner.Kernel.Deadline.t() | nil,
  run_started_metadata: map(),
  session_profile: map() | nil,
  workflow_environment: PtcRunner.Kernel.WorkflowEnvironment.t()
}
```

# `close_provider_session`

```elixir
@spec close_provider_session(t()) :: :ok | {:error, :provider_cleanup_failed}
```

Closes the one provider session and its reverse-order cleanup stack.

Cleanup is bounded by the session's sealed limit. Exceptions, timeouts, and
non-success results are normalized to `:provider_cleanup_failed` without
exposing provider details.

# `new`

```elixir
@spec new(keyword()) ::
  {:ok, t()}
  | {:error,
     :invalid_run_config
     | :mission_inventory_exceeded
     | :run_started_metadata_exceeded
     | {:terminal_payload_capacity_exceeded, pos_integer(), pos_integer()}}
```

Constructs a run configuration and rejects missing or unknown fields.

---

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