PtcRunner.Kernel.Limits (PtcRunner v0.15.0)

Copy Markdown View Source

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 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.

Summary

Types

t()

Functions

defaults()

Returns the complete application-independent default limit set.

fetch(limits, name)

Reads one cataloged field from a valid limits value.

installed(overrides \\ %{})

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

installed_defaults()

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

name(value)

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

names()

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

new(overrides \\ %{})

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

valid?(limits)

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

Types

t()

@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()
}

Functions

defaults()

@spec defaults() :: t()

Returns the complete application-independent default limit set.

fetch(limits, name)

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

Reads one cataloged field from a valid limits value.

installed(overrides \\ %{})

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

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

installed_defaults()

@spec installed_defaults() :: t()

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

name(value)

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

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

names()

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

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

new(overrides \\ %{})

@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?(limits)

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

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