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

Shipped PTC-Lisp libraries as explicit Kernel components.

Available component IDs are `kernel`, `runtime`, `cap`, `workflow.event`,
`llm`, `agent.native`, `agent.core`, `agent.failure`, `agent.feedback`,
`agent.machine`, `agent.retry`, `agent.prompt`, `agent.main`, `result`,
`analysis`, `debug.nav`, and `prompt.audit`.

`agent.main` is a generic entry wrapper: a manifest names `agent.main/run`
and supplies `task` and `agent` through input, instead of every application
repeating the same `agent.core` call. It is domain-blind by construction —
it forwards two input keys and never learns what the task is about. It
validates each model-authored terminal candidate against the manifest result
contract while a bounded correction turn can still run, then returns the
raw application value; callers of `agent.core/run` retain its explicit
`%{"ok" => true, "value" => value}` success envelope by default.
`agent.core/run-value` is the composable variant: it returns the same
model-authored value to its PTC-Lisp caller without terminating the outer
workflow, allowing an evaluator to judge the answer before returning. It and
`agent.core/run-outcome` remain raw by default; either may explicitly select
one application-declared named phase-return contract for in-loop standalone
handoff validation and bounded correction.

`analysis` and `debug.nav` are the two navigation surfaces over one immutable
run-evidence capture, and a mission installs one or the other. `analysis`
binds the stable `analysis-runs`/`analysis-open`/`analysis-read`/
`analysis-counters` capability names a REPL analysis profile grants.
`debug.nav` adds `follow` and binds a manifest-installed snapshot provider,
which names its operations `<alias>.runs`/`<alias>.open`/`<alias>.read`/
`<alias>.counters`; the mission must therefore select its correlated
inspection snapshot provider under the conventional alias `debug.nav`.
`counters` is a thin unwrap of the captured canonical trace aggregate;
`follow` takes one typed relationship from an evidence item and reads its
exact target collection and filters, refusing an unavailable or filterless
relationship and any caller filter beyond `limit` and `cursor`. Neither adds
host authority or diagnosis policy: `follow` returns the original
relationship beside the unchanged native page envelope, so cursors,
completeness, and relationship state survive the hop.

`cap` is `:discoverable` rather than `:prompt`. Its envelope and pagination
helpers compose capabilities for other libraries and stay out of the prompt
inventory; evaluated code still finds them with `(dir "cap")` and reads them
with `(doc "cap/fold-pages")`. `unwrap!` fails the program on an error
envelope rather than returning it. `fold-pages` is the one traversal helper:
it reduces page items into bounded caller state, preserves a resumable cursor
at its explicit page bound, and rejects changed snapshots or cursor cycles
observed within one invocation without retaining source-sized resume history.

`agent.failure` is also `:discoverable`. It is generated from
`PtcRunner.Kernel.LLMFailureCatalog` and exports one pure `classify`
function over the existing bounded LLM envelope. Classification does not add
a field, tool call, or fail-fast evidence; `kernel-llm-provider-failure`
remains the consume boundary.

`agent.machine` is `:discoverable` as well: a pure constructor/advance reducer
for the shipped agent loop. Visibility is not an authority boundary; the
exports remain callable. It is not an application customization API.

Fetching one component with `component/1` does not expand its dependencies,
and `PtcRunner.Kernel` refuses to compile an incomplete set. Manifests and
`resolve_components/1` expand installed-library selections transitively;
direct callers of `compile_bundle/1` must supply the resulting closed set.

Fetching a component grants no capability. The host still compiles the
selected closed component set and supplies the capabilities required by its
exports when assembling an environment.

# `component`

```elixir
@spec component(binary()) ::
  {:ok, PtcRunner.Kernel.Component.t()} | {:error, :unknown_library}
```

Returns one shipped component by its stable component ID.

# `component_ids`

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

Returns every shipped component ID in lexical order.

# `components`

```elixir
@spec components([binary()]) ::
  {:ok, [PtcRunner.Kernel.Component.t()]} | {:error, :unknown_library}
```

Returns shipped components in the requested order.

# `resolve_components`

```elixir
@spec resolve_components([PtcRunner.Kernel.Component.t() | {:library, binary()}]) ::
  {:ok, [PtcRunner.Kernel.Component.t()]}
  | {:error,
     :invalid_component_selection
     | :duplicate_library_selection
     | :duplicate_component_id
     | :unknown_library
     | :missing_component_dependency
     | :component_cycle
     | :local_library_collision
     | :component_limit_exceeded}
```

Resolves local components and explicit shipped-library selections.

Explicit library selections must be unique. Installed dependency closure is
expanded from this module only, transitive duplicates coalesce, and local
component IDs may not collide with any installed ID. The result is ordered
lexically by component ID. Graph validation and dependency ordering belong
to bounded bundle compilation, so missing local dependencies and cycles
remain phase-4 bundle failures instead of being flattened into application
acquisition.

---

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