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

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.

# `built`

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

# `build`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

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