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

Normalized positive hard ceilings for one Kernel run.

Every field, default, accepted range, scope, and identity rule comes from
`PtcRunner.Kernel.LimitCatalog`. Ordinary rows have no disabled or infinite
form. Optional rows are `nil` until the host enables them.
`new/1` accepts only cataloged fields and overlays them on `defaults/0`.

The generated [Kernel limits reference](kernel-limits-reference.md) lists the
meaning, unit, defaults, installed ceilings, range, and scope of every row.

The installed-only timeouts are cataloged and sealed in this boundary before
the later provider-lifecycle and doctor phases begin consuming them. Merely
constructing a `Limits` value does not enforce those future operations.

`defaults/0` are the effective limits used when a manifest does not request
narrower values. `installed_defaults/0` are the larger host-controlled
ceilings used by manifest-backed frontends. A host may supply another
complete `Limits` value as its installation ceiling. Manifests can narrow
only catalog rows scoped `:manifest_narrowable` or
`:optional_manifest_narrowable`; installed-only values are copied from the
host unchanged.

Catalog validation covers each field independently, including the minimum
event payload needed by bounded terminal events. Manifest loading also
validates the normal trace fields together after host/application resolution:
the effective count must retain one ordinary event plus the two terminal
events, and the byte budget must retain one complete maximum-size
`run-started` event in addition to `PtcRunner.Kernel.EventSink`'s measured
terminal reserve. Private trace policy reserves one terminal envelope so a
capacity refusal can still produce a complete retained trace.

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.Limits{
  capability_argument_bytes: pos_integer(),
  capability_result_bytes: pos_integer(),
  doctor_connectivity_timeout_ms: pos_integer(),
  entry_source_bytes: pos_integer(),
  evaluation_admission_timeout_ms: pos_integer(),
  evaluation_heap_words: pos_integer(),
  evaluation_history_bytes: pos_integer(),
  evaluation_loop_iterations: pos_integer() | nil,
  evaluation_memory_bytes: pos_integer(),
  evaluation_timeout_ms: pos_integer(),
  event_payload_bytes: pos_integer(),
  live_provider_tasks: pos_integer(),
  llm_cost_microusd: pos_integer() | nil,
  llm_request_output_tokens: pos_integer(),
  llm_request_timeout_ms: pos_integer(),
  llm_total_tokens: pos_integer() | nil,
  local_preflight_timeout_ms: pos_integer(),
  mission_capability_calls: pos_integer(),
  mission_capability_calls_per_name: pos_integer(),
  normal_event_bytes: pos_integer(),
  normal_event_count: pos_integer(),
  parallel_timeout_ms: pos_integer(),
  protocol_errors: pos_integer(),
  provider_cleanup_timeout_ms: pos_integer(),
  provider_heap_words: pos_integer(),
  run_duration_ms: pos_integer(),
  selection_validation_timeout_ms: pos_integer(),
  subordinate_evaluations: pos_integer(),
  subordinate_source_bytes: pos_integer(),
  subordinate_source_checks: pos_integer(),
  terminal_result_bytes: pos_integer(),
  workflow_capability_calls: pos_integer(),
  workflow_capability_calls_per_name: pos_integer(),
  workflow_heap_words: pos_integer(),
  workflow_loop_iterations: pos_integer() | nil,
  workflow_timeout_ms: pos_integer()
}
```

# `defaults`

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

Returns the complete application-independent default limit set.

# `fetch`

```elixir
@spec fetch(t(), binary() | atom()) :: {:ok, pos_integer() | nil} | :error
```

Reads one cataloged field from a valid limits value.

# `installed`

```elixir
@spec installed(map() | keyword()) :: {:ok, t()} | {:error, :invalid_limits}
```

Builds complete host-installed ceilings from the catalog's installed defaults.

# `installed_defaults`

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

Returns practical host ceilings for manifest-backed model and connector runs.

# `name`

```elixir
@spec name(term()) :: {:ok, atom()} | :error
```

Resolves one public limit name to its field, or `:error` when unknown.

# `names`

```elixir
@spec names() :: [binary()]
```

Returns every public limit name, sorted, for operator-facing validation.

# `new`

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

Builds a complete limit set by applying atom-keyed overrides to the defaults.

Unknown fields and values outside their cataloged inclusive range are
rejected.

# `valid?`

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

Checks that a complete limits struct contains only positive integer ceilings.

---

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