PtcRunner.Kernel.RunBuilder (PtcRunner v0.14.0)

Copy Markdown View Source

Shared path-free request construction and execution path.

Filesystem and memory adapters first acquire a sealed PtcRunner.Kernel.RunRequest. The builder then resolves trusted provider names, compiles separate workflow and mission bundles, assembles their environments, starts the configured event sink, and produces the same PtcRunner.Kernel.RunConfig accepted by direct Elixir embedding. Relative artifact destinations are anchored once before preflight; the sealed publication authority retains them while the run configuration and outcome remain path-free.

Provider-free requests cross the same path-free PtcRunner.Kernel.RunCoordinator phases 4 and 5 as command frontends, and downstream assembly consumes the resulting sealed PreparedRun directly. Pure option validation completes before that one-way consumption. The Mix one-shot path performs this assembly inside the coordinator's execution-session owner so the prepared run and both sinks share one caller-death boundary. A provider-bearing prepared run is preflighted the same way, and its active session is passed here for runtime assembly. One-shot runs open that session inside the execution-session owner and call build_active_owned/7 with the owner's sinks, then complete through execute_built/1. Manifest REPLs use the same prepared active build, retain its one provider session behind an opening owner, and transfer that handle with the run state to the REPL owner. Provider-free REPLs keep the same owner boundary while omitting only the provider session. PtcRunner.Kernel.ProviderAcquisition then runs the selected providers' shared preparation and dependency-ordered acquisition barrier. It plans that barrier from the preparation and the catalog it was validated against, which is why build_active_owned/7 takes the catalog beside the prepared run, and it acquires against the credentials phase-8 step 5 already resolved. Active preparation, preflight, and acquisition are owner-linked and bounded by the session's run deadline; preflight releases share the provider-cleanup budget. Registry builders no longer open a second provider-session owner.

A provider-bearing build remains owned by its build creator until execution binds it to a Runner or REPL lifecycle owner. The creator must remain alive until that bind or until close/1; returning an unstarted build from a short-lived task is not an ownership transfer.

One-shot execution freezes its result, disclosure class, contract decision, terminal events, and optional inspection records in a sealed PtcRunner.Kernel.ExecutionOutcome. Both sinks stop before the separate publication step consumes that path-free evidence together with the sealed, preflighted PtcRunner.Kernel.PublicationAuthority retained by the build.

Summary

Functions

Builds an entry expression and complete run configuration from a sealed request.

Builds a provider-free run directly from the sealed phase-4/5 result.

Closes a built but unexecuted configuration and its event sink.

Types

built()

@type built() :: %{
  entry_source: binary(),
  config: PtcRunner.Kernel.RunConfig.t(),
  publication_authority: PtcRunner.Kernel.PublicationAuthority.t(),
  result_projection: :native | :json,
  build_binding: binary()
}

Functions

build(request, registry, opts \\ [])

@spec build(
  PtcRunner.Kernel.RunRequest.t(),
  PtcRunner.Kernel.ProviderRegistry.t(),
  keyword()
) ::
  {:ok, built()} | {:error, term()}

Builds an entry expression and complete run configuration from a sealed request.

build_prepared(prepared, registry, opts \\ [])

@spec build_prepared(
  PtcRunner.Kernel.PreparedRun.t(),
  PtcRunner.Kernel.ProviderRegistry.t(),
  keyword()
) ::
  {:ok, built()} | {:error, term()}

Builds a provider-free run directly from the sealed phase-4/5 result.

close(config)

@spec close(
  %{
    config: PtcRunner.Kernel.RunConfig.t(),
    publication_authority: PtcRunner.Kernel.PublicationAuthority.t()
  }
  | PtcRunner.Kernel.RunConfig.t()
) :: :ok | {:error, :provider_cleanup_failed | :publication_cleanup_failed}

Closes a built but unexecuted configuration and its event sink.