PtcRunner.Kernel.RunConfig (PtcRunner v0.14.0)

Copy Markdown View Source

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

Summary

Types

t()

Functions

close_provider_session(run_config)

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

new(opts)

Constructs a run configuration and rejects missing or unknown fields.

Types

t()

@type t() :: %PtcRunner.Kernel.RunConfig{
  claim_id: reference(),
  connector_snapshots: [map()],
  event_sink: PtcRunner.Kernel.EventSink.t(),
  event_sink_owner: pid(),
  input: map(),
  inspection_sink: PtcRunner.Kernel.InspectionSink.t() | nil,
  inspection_sink_owner: pid() | nil,
  labels: map(),
  limits: PtcRunner.Kernel.Limits.t(),
  missions: %{
    required(binary()) => %{
      environment: PtcRunner.Kernel.MissionEnvironment.t(),
      inventory: term()
    }
  },
  provider_session: PtcRunner.Kernel.ProviderSession.t() | nil,
  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()
}

Functions

close_provider_session(run_config)

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

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

Constructs a run configuration and rejects missing or unknown fields.