ptc_runner

<!-- Auto-generated — do not edit by hand -->
# Shipped prelude reference

> **Warning:** This file is auto-generated by `mix ptc.gen_docs` from the shipped component catalog and compiled PTC-Lisp exports.
> Manual edits will be overwritten. Edit `PtcRunner.Kernel.Library`, the hand-authored sources under `priv/preludes/kernel/`, `PtcRunner.Kernel.LLMFailureCatalog` (for generated `agent.failure`), or `Mix.Tasks.Ptc.GenDocs` instead.

PtcRunner ships 17 reusable PTC-Lisp **components** with 61 public exports. A component is one named source module with one namespace. A **prelude** is the immutable compiled aggregate of the components selected for a workflow or mission, including their dependency closure.

Private `defn-` helpers are deliberately absent below. Public `defn` functions and `def` constants are derived from the same compiler records used by analysis, evaluation, introspection, and model inventory rendering.

## Choose a component

| Need | Start with |
| --- | --- |
| Generic manifest agent entry with result-contract correction | `agent.main` |
| Composable provider-neutral agent loop | `agent.core` |
| Direct provider-neutral model requests | `llm` |
| Subordinate mission evaluation and validation | `kernel` |
| Capability discovery, envelope handling, or bounded pagination | `cap` |
| Stable run-analysis profile navigation | `analysis` |
| Manifest-installed private snapshot navigation | `debug.nav` |
| Rendered agent prompt measurement | `prompt.audit` |

## Use and compose components

Select a shipped component as a library and declare it as a dependency of every local component that calls it:

```json
"components": [
  {"id": "my.workflow", "path": "workflow.clj", "dependencies": ["kernel"]},
  {"library": "kernel"}
]
```

Selecting a library expands its transitive shipped dependencies. Dependency declarations control which namespaces may call each other during compilation; they do not grant capabilities. Environment assembly must satisfy every backing requirement of the resolved exports.

## Authority and supported environments

The export sections list compile-time `tool:<name>` backing requirements. How they are satisfied depends on the operation family:

| Requirement family | Supplied by | Supported environment |
| --- | --- | --- |
| `tool:kernel-*`, `tool:workflow-annotate` | Reserved Kernel operations; applications cannot install or replace them as providers | Workflow |
| `tool:runtime-*`, `tool:cap-*` | Reserved Kernel operations | Workflow or mission |
| `tool:llm-request` | A selected live or replay model provider | Workflow |
| `tool:analysis-*` | A host-selected run-analysis profile | Its bounded analysis mission |
| `tool:debug.nav.*` | The correlated inspection snapshot provider selected under alias `debug.nav` | Mission |

Pure exports show no backing requirements. Requirements validate authority; they never create it. A component with reserved workflow requirements cannot be moved into a mission merely by selecting the library there.

Effects below use the same conservative, environment-independent projection as `(doc ...)` and `(export-meta ...)`: an export that reaches a capability is `unknown` unless its chain declares `write`. The authoritative model-visible effect belongs to the assembled mission inventory, where installed capability effects may resolve that value to `read` or `write`.

`:prompt` exports appear in model inventory. `:discoverable` exports stay out of that prompt inventory but remain callable and can be found with `(dir)`, `(dir "namespace")`, `(apropos "term")`, `(doc "namespace/name")`, `(export-meta "namespace/name")`, and `(source namespace/name)`. `apropos` and `doc` additionally cover installed callable capabilities, fixed built-ins, and the bounded Java surface; `dir`, `export-meta`, and `source` remain attached-prelude views. At Kernel boundaries, an exact `doc` miss for an indexed shipped public export can identify its unattached owning library. The exact index is diagnostic only and is never searched by `apropos`. Hiding an export or capability from the prompt does not narrow authority or runtime discovery.

## Customize or replace a component

Use a new component ID for ordinary application-specific helpers or policies. A local component cannot shadow a selected shipped library ID; such collisions are rejected.

A [component override](guides/evaluating-with-replay.md#evaluate-the-candidate-without-installing-it) can evaluate hash-checked replacement source for one component already selected by the manifest. The override is a run invocation option, not a permanent manifest library installation. For a permanently customized agent prompt in ordinary manifest composition, use custom loop and prompt components under new IDs rather than depending on the shipped `agent.core`, whose dependency remains the shipped `agent.prompt` ID.

The resolved prelude is frozen for the run. Changed component source must be compiled into a new bundle, and traces identify the effective component and aggregate hashes.

## Dependency overview

| Component | Purpose | Visibility | Direct dependencies | Directly used by |
| --- | --- | --- | --- | --- |
| `agent.main` | Generic workflow entry for scripted agents. | `prompt` | `agent.core` | — |
| `agent.core` | Provider-neutral scripted PTC-Lisp agent loop. | `prompt` | `agent.feedback`, `agent.machine`, `agent.native`, `agent.prompt`, `kernel`, `llm`, `result`, `workflow.event` | `agent.main` |
| `agent.prompt` | Domain-blind system-prompt policy for agent.core. | `discoverable` | `kernel` | `agent.core`, `agent.machine` |
| `agent.feedback` | Bounded correction messages for agent workflows. | `prompt` | — | `agent.core`, `agent.machine` |
| `agent.retry` | Small deterministic agent retry policy. | `prompt` | — | `agent.machine` |
| `agent.native` | Strict run_ptc_lisp model-action protocol. | `prompt` | — | `agent.core` |
| `agent.failure` | Closed classification of admitted LLM provider, protocol, and whole-request timeout envelopes. | `discoverable` | — | `agent.machine` |
| `agent.machine` | Pure agent-loop reducer: immutable context/state and closed event-to-command transitions. Visibility is presentation only; exports remain callable and are not an authority boundary. | `discoverable` | `agent.failure`, `agent.feedback`, `agent.prompt`, `agent.retry`, `result` | `agent.core` |
| `kernel` | Explicit subordinate evaluation helpers. | `prompt` | — | `agent.core`, `agent.prompt` |
| `llm` | Provider-neutral language-model requests. | `prompt` | — | `agent.core` |
| `cap` | Capability discovery and envelope composition helpers. | `discoverable` | — | `analysis`, `debug.nav` |
| `runtime` | Read-only enforced run-resource snapshots. | `prompt` | — | — |
| `result` | Uniform opt-in workflow result values. | `prompt` | — | `agent.core`, `agent.machine` |
| `workflow.event` | Bounded workflow-authored semantic annotations. | `prompt` | — | `agent.core` |
| `analysis` | Bounded navigation over one immutable run-evidence capture. | `prompt` | `cap` | — |
| `debug.nav` | Typed navigation over one immutable private run-evidence capture. The mission must select its correlated inspection snapshot provider under the conventional alias debug.nav. | `prompt` | `cap` | — |
| `prompt.audit` | Size measurement for a rendered agent system prompt.  `agent.prompt/render` interleaves authored instruction text with manifest-derived API text, so one byte count for the whole prompt cannot say which of the two an edit moved. These functions take the rendered string — from a recorded run, a committed fixture, or any other source — and answer three questions about it: which segments it is made of, how large each one is, and what changed between two versions.  Every function is pure and takes a string. Nothing here reads a run, calls a capability, or assembles a manifest, so the same numbers are available to a REPL session reading recorded evidence and to a test guarding a fixture. | `discoverable` | — | — |

## Agent entry points

### `agent.main`

Generic workflow entry for scripted agents.

- **Visibility:** `prompt`
- **Direct dependencies:** `agent.core`
- **Selecting it also installs:** `agent.core`, `agent.failure`, `agent.feedback`, `agent.machine`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event`
- **Directly used by:** —

```json
{"library": "agent.main"}
```

#### Public exports

##### `agent.main/run`

```clojure
(agent.main/run input)
```

Runs `agent.core` from a manifest input, so a manifest can name this entry
directly instead of every application repeating the same wrapper.

`task` is the workflow's instruction and `agent` its loop configuration. Both
come from input, so this stays domain-blind: it never learns what the task is
about, and adding a new application needs no change here. The application
entry returns the model-authored value directly so a manifest result contract
describes that value rather than agent.core's default success envelope.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(input {task :string, agent {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

### `agent.core`

Provider-neutral scripted PTC-Lisp agent loop.

- **Visibility:** `prompt`
- **Direct dependencies:** `agent.feedback`, `agent.machine`, `agent.native`, `agent.prompt`, `kernel`, `llm`, `result`, `workflow.event`
- **Selecting it also installs:** `agent.failure`, `agent.feedback`, `agent.machine`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event`
- **Directly used by:** `agent.main`

```json
{"library": "agent.core"}
```

#### Public exports

##### `agent.core/fail-outcome`

```clojure
(agent.core/fail-outcome outcome)
```

Returns a successful `run-outcome` outcome unchanged and aborts any other
canonical outcome with its authenticated provider or subject diagnostic.
Use this after inspecting an outcome and deciding not to retry or fail over.
Only evidence retained by the Kernel can produce a specialized public
diagnostic; arbitrary caller maps remain ordinary explicit failures.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(outcome :map) -> :map`
- **Backing requirements:** `tool:kernel-agent-outcome-failure`, `tool:kernel-llm-provider-failure`, `tool:kernel-runtime-limit-failure`

##### `agent.core/run`

```clojure
(agent.core/run task cfg)
```

Runs the agent loop as a terminal workflow entry.

The default result is a success envelope. Set `result_envelope` to false for
a raw application value. The exact value this entry returns is validated
against the manifest result contract while a correction turn remains: the
envelope by default, or the raw value when `result_envelope` is false. Use
`run-value` when the caller must continue after the model-authored value
returns, and `run-result-value` when that raw value is itself the
contract-shaped application result.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?, result_envelope :bool?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

##### `agent.core/run-outcome`

```clojure
(agent.core/run-outcome task cfg)
```

Runs the agent loop and distinguishes model-authored completion from a
bounded subject-attributable failure or a bounded provider failure. The
returned outcome is workflow data; this entry does not validate against the
manifest result contract. Set `return_contract` to a name declared under
`contracts.phase_return_schemas` to validate each explicit return inside this
standalone loop while correction turns remain.

Provider failures return `{:status :provider-failure :error error :model alias}`
with the complete bounded LLM envelope. The closed `kind` and `reason` are
facts for workflow policy; this entry does not choose retry, failover, or
abort. Restarting with another alias starts another loop and does not resume
the previous transcript. Subject failures that need authenticated later
propagation include an opaque `:failure-token`; preserve it by passing the
original outcome to `fail-outcome`.

Set `verify` to a workflow-owned function receiving a candidate map with
`:status :candidate`, `:value`, and optional retained programs. It returns a
map with string `status`: accepted, rejected, or unresolved. Rejected and
unresolved reports require a nonblank `feedback` string of at most 2048
characters. Optional `evidence` remains workflow data. The final outcome
carries the report under `:verification`; a failed verification never
returns `:status :returned` or a top-level `:value`.

`max_corrections` defaults to 1 (0 through 128). Rejection keeps the same
transcript and consumes remaining max_turns; unresolved stops immediately.
No correction follows a write or unknown effect in any prior agent turn.
The callback runs under workflow authority and deadlines: keep it read-only
and explicitly narrow authority with kernel/eval-with when needed. Callback
errors and invalid reports fail the workflow. Verification is standalone,
run-outcome only, and follows return_contract validation when selected.

Set `retain_programs` to an integer from 1 through 128 to attach admitted
generated programs on the returned outcome. Omitted or nil keeps the current
outcome shape. When set, every returned outcome includes `:programs` and
`:programs-omitted`. Retention keeps the newest complete entries that fit
both the requested count and a fixed 2,000,000 UTF-8-byte source ceiling.
Each entry also carries a bounded execution summary; ordinary observations
are capped at 2,048 characters and raw evaluation values are never retained.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, return_contract :any?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?, retain_programs :any?, verify :any?, max_corrections :any?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-outcome-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

##### `agent.core/run-phased-result-value`

```clojure
(agent.core/run-phased-result-value task cfg)
```

Runs a sequence of bounded mission phases while retaining the exact
correlated model and evaluation transcript. At each host-controlled phase
boundary, the system prompt is rebuilt from the next mission's authority and
that phase's instruction is appended as a user message. A return closes any
non-final phase and is retained as evidence; only the final phase can complete
the agent with a contract-valid result. A terminal-only phase rejects any
parsed program whose single top-level form is not return or fail before
mission evaluation, and only the final phase may declare terminal_only.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, phases [{mission :string, max_turns :int, instruction :string?, terminal_only :bool?, return_contract :string?}], max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

##### `agent.core/run-result-value`

```clojure
(agent.core/run-result-value task cfg)
```

Runs the agent loop and validates the raw model-authored value against the
manifest result contract before returning it to the calling workflow. Use
this when that raw value is itself the final contract-shaped application
result.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

##### `agent.core/run-value`

```clojure
(agent.core/run-value task cfg)
```

Runs the agent loop and returns its model-authored value to the calling
PTC-Lisp function. Unlike `run`, this does not terminate the outer program
and does not validate against the manifest result contract, so an application
can validate or score the answer before returning. Set `return_contract` to
a declared named phase-return contract when the value crossing back to the
workflow must be checked and corrected inside this standalone loop.

Subject failures and provider failures retain the historical fail behavior.
Evaluators that need to record those attempts use `run-outcome`.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, return_contract :any?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-phase-return-contract-failure`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`

## Agent loop policy

### `agent.prompt`

Domain-blind system-prompt policy for agent.core.

- **Visibility:** `discoverable`
- **Direct dependencies:** `kernel`
- **Selecting it also installs:** `kernel`
- **Directly used by:** `agent.core`, `agent.machine`

```json
{"library": "agent.prompt"}
```

#### Public exports

##### `agent.prompt/initial-state`

```clojure
(agent.prompt/initial-state cfg)
```

Creates the initial domain-blind prompt-policy state from agent configuration.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.prompt/render`

```clojure
(agent.prompt/render state)
```

Renders the system prompt, or the capability error envelope that prevented it.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-model-context`

##### `agent.prompt/transition`

```clojure
(agent.prompt/transition state event)
```

Advances prompt-policy state after one agent-loop event.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

### `agent.feedback`

Bounded correction messages for agent workflows.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`, `agent.machine`

```json
{"library": "agent.feedback"}
```

#### Public exports

##### `agent.feedback/capability-error`

```clojure
(agent.feedback/capability-error evaluation)
```

Renders correction guidance for a safely retryable capability failure.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/evaluation-error`

```clojure
(agent.feedback/evaluation-error evaluation)
```

Renders bounded correction guidance for a failed evaluation.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/non-retryable`

```clojure
(agent.feedback/non-retryable evaluation)
```

Renders closing guidance after a failure whose external effects may be unsafe to repeat.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/phase-result-contract`

```clojure
(agent.feedback/phase-result-contract validation)
```

Renders bounded correction guidance for an invalid phase handoff.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/protocol-error`

```clojure
(agent.feedback/protocol-error action)
```

Renders correction guidance for an invalid model action.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/result-contract`

```clojure
(agent.feedback/result-contract validation)
```

Renders bounded correction guidance for an invalid application result.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/success`

```clojure
(agent.feedback/success evaluation max-chars)
```

Renders a bounded, explicitly untrusted observation from a successful evaluation. Value-preview truncation names `*1` only for history-committing ordinary results; omitted println output is reported independently and is never attributed to `*1`.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/terminal-source-required`

```clojure
(agent.feedback/terminal-source-required check)
```

Renders correction guidance for a program rejected by a terminal-only phase.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.feedback/turn-budget`

```clojure
(agent.feedback/turn-budget turns-remaining consolidate-at-turns-remaining)
```

Renders model-visible pacing guidance outside the cached system prompt.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(turns_remaining :int, consolidate_at_turns_remaining :int?) -> :string`
- **Backing requirements:** —

### `agent.retry`

Small deterministic agent retry policy.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.machine`

```json
{"library": "agent.retry"}
```

#### Public exports

##### `agent.retry/backoff-ms`

```clojure
(agent.retry/backoff-ms turn cfg)
```

Returns the bounded deterministic retry delay for a turn.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.retry/retry?`

```clojure
(agent.retry/retry? turn max-turns)
```

Returns whether another agent turn remains within the configured bound.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

### `agent.native`

Strict run_ptc_lisp model-action protocol.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`

```json
{"library": "agent.native"}
```

#### Public exports

##### `agent.native/normalize`

```clojure
(agent.native/normalize response max-program-chars)
```

Normalizes one provider response into a usable tool call or a bounded terminal/recoverable action. A complete run_ptc_lisp call wins even when the provider reports output truncation.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `agent.native/tool-schema`

```clojure
(agent.native/tool-schema)
```

Returns the strict provider-neutral run_ptc_lisp tool schema.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

### `agent.failure`

Closed classification of admitted LLM provider, protocol, and whole-request timeout envelopes.

- **Visibility:** `discoverable`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.machine`

```json
{"library": "agent.failure"}
```

#### Public exports

##### `agent.failure/classify`

```clojure
(agent.failure/classify error)
```

Returns true when `error` is an admitted recoverable LLM envelope.

Inspects only `kind` and `reason`. Does not add a field to the envelope or
consume Kernel evidence.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Contract:** `(error :any) -> :bool`
- **Backing requirements:** —

### `agent.machine`

Pure agent-loop reducer: immutable context/state and closed event-to-command
transitions. Visibility is presentation only; exports remain callable and are
not an authority boundary.

- **Visibility:** `discoverable`
- **Direct dependencies:** `agent.failure`, `agent.feedback`, `agent.prompt`, `agent.retry`, `result`
- **Selecting it also installs:** `agent.failure`, `agent.feedback`, `agent.prompt`, `agent.retry`, `kernel`, `result`
- **Directly used by:** `agent.core`

```json
{"library": "agent.machine"}
```

#### Public exports

##### `agent.machine/advance`

```clojure
(agent.machine/advance machine event)
```

One pure transition. Returns a closed command; never calls LLM, Kernel, tools, or fail.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Contract:** `(machine :map, event :any) -> :any`
- **Backing requirements:** —

##### `agent.machine/start`

```clojure
(agent.machine/start task context)
```

Constructs immutable context and initial loop state. Performs no effects.
Returns `{:op :ok :machine ...}` or a host-failure command.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Contract:** `(task :string, context :map) -> :any`
- **Backing requirements:** —

## Evaluation and models

### `kernel`

Explicit subordinate evaluation helpers.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`, `agent.prompt`

```json
{"library": "kernel"}
```

#### Public exports

##### `kernel/check-source`

```clojure
(kernel/check-source mission source)
```

Check bounded dynamic source against the live mission environment without executing it.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-check-source`

##### `kernel/check-terminal-source`

```clojure
(kernel/check-terminal-source mission source)
```

Check that bounded dynamic source compiles and consists of exactly one top-level return or fail form, without executing it.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-check-source`

##### `kernel/eval`

```clojure
(kernel/eval mission program-value)
```

Evaluate an opaque static Program in the mission environment.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`

##### `kernel/eval-source`

```clojure
(kernel/eval-source mission source)
```

Evaluate bounded dynamic source text in the mission environment.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`

##### `kernel/eval-source-with`

```clojure
(kernel/eval-source-with mission source params)
```

Evaluate bounded dynamic source with JSON parameters at data/params.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`

##### `kernel/eval-with`

```clojure
(kernel/eval-with mission program-value params)
```

Evaluate an opaque static Program with JSON parameters at data/params.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`

##### `kernel/mission-inventory`

```clojure
(kernel/mission-inventory mission)
```

Return the frozen prompt-facing mission inventory JSON, including data grants.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-inventory`

##### `kernel/mission-model-context`

```clojure
(kernel/mission-model-context mission)
```

Return the compact deterministic mission context for the model prompt.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-model-context`

##### `kernel/phase-return-contract-presentation`

```clojure
(kernel/phase-return-contract-presentation name)
```

Resolve one named phase-return contract and return its model projection.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-result-contract`

##### `kernel/result-contract-presentation`

```clojure
(kernel/result-contract-presentation)
```

Return the bounded renderer-neutral application result contract, or nil.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-result-contract`

##### `kernel/validate-phase-return`

```clojure
(kernel/validate-phase-return name value)
```

Validate an explicit phase or standalone handoff return against its named contract.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-result-contract`

##### `kernel/validate-result`

```clojure
(kernel/validate-result value)
```

Validate one candidate against the manifest's application result contract.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-result-contract`

### `llm`

Provider-neutral language-model requests.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`

```json
{"library": "llm"}
```

#### Public exports

##### `llm/request`

```clojure
(llm/request request)
```

Send a provider-neutral request. An optional schema key requests
structured output: success is a structured_output object with optional
tokens, never encoded content. Tools and schema together are invalid.
Tool calls use id, name, and args; token usage may include input, output,
cache_creation, cache_read, and fixed-point total_cost as a USD currency and
integer microunits object.

On success this returns the model response value. Provider failures,
including a replay miss, are returned as error envelopes with :status
:error rather than failing the evaluation. Branch on :status and fail, or
call cap/unwrap! on the raw tool/llm-request envelope, so an unserved call
cannot look like a result.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:llm-request`

## Workflow helpers

### `cap`

Capability discovery and envelope composition helpers.

- **Visibility:** `discoverable`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `analysis`, `debug.nav`

```json
{"library": "cap"}
```

#### Public exports

##### `cap/describe`

```clojure
(cap/describe name)
```

Returns the installed description for one capability name.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:cap-describe`

##### `cap/fold-pages`

```clojure
(cap/fold-pages fetch step initial opts)
```

Reduces cursor-paginated items into bounded caller-owned state.

`fetch` receives nil for the first page or the opaque cursor supplied in
`opts`. `step` receives accumulator then item. Every page must contain
`items`, `next_cursor`, and a stable non-empty `snapshot_hash`.

`opts` requires a positive `max_pages`. Resuming with `cursor` also requires
the expected `snapshot_hash`. A page-bound stop returns `complete?` false and
preserves `next_cursor`, so another evaluation can continue without retaining
prior pages. Keep the accumulator bounded; pagination does not make an
unbounded collection safe. Repeated cursors within one invocation fail instead
of looping; a resumed invocation does not retain source-sized cursor history.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `cap/list`

```clojure
(cap/list)
```

Lists capabilities installed in the current environment.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:cap-list`

##### `cap/unwrap!`

```clojure
(cap/unwrap! response)
```

Returns a capability response's value, failing the program on any error.

Capability calls answer {:status :ok :value ...} or an error envelope. A
wrapper that returns the envelope on failure makes every caller re-check it,
and a caller that forgets treats an error map as ordinary data. This fails
instead, so an unhandled provider error stops the program rather than
flowing onward as a plausible-looking result.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

### `runtime`

Read-only enforced run-resource snapshots.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** —

```json
{"library": "runtime"}
```

#### Public exports

##### `runtime/remaining`

```clojure
(runtime/remaining)
```

Returns the enforced run-resource allowance remaining.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:runtime-remaining`

##### `runtime/usage`

```clojure
(runtime/usage)
```

Returns the enforced run-resource usage snapshot.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:runtime-usage`

### `result`

Uniform opt-in workflow result values.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`, `agent.machine`

```json
{"library": "result"}
```

#### Public exports

##### `result/error`

```clojure
(result/error kind reason)
```

Builds a standard opt-in workflow error envelope.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `result/ok`

```clojure
(result/ok value)
```

Wraps a successful workflow value in the standard opt-in result envelope.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `result/ok?`

```clojure
(result/ok? result)
```

Returns whether a standard result envelope represents success.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —

### `workflow.event`

Bounded workflow-authored semantic annotations.

- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`

```json
{"library": "workflow.event"}
```

#### Public exports

##### `workflow.event/annotate`

```clojure
(workflow.event/annotate annotation-type data)
```

Emits one bounded workflow-authored semantic annotation.

A refused well-formed annotation — a string type or data shape that is
not in the traces vocabulary — returns {:status :error :kind
:invalid_annotation :reason :invalid_workflow_annotation} rather than
failing the evaluation. Accepted types and keys are the finite vocabulary
published by ptc docs traces.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:workflow-annotate`

## Run evidence

### `analysis`

Bounded navigation over one immutable run-evidence capture.

- **Visibility:** `prompt`
- **Direct dependencies:** `cap`
- **Selecting it also installs:** `cap`
- **Directly used by:** —

```json
{"library": "analysis"}
```

#### Public exports

##### `analysis/counters`

```clojure
(analysis/counters filters)
```

Returns trace counters for a filtered run cohort, including adapter-attested model usage. Accepted keys are status, run_id, trace_id, tags, name, bundle, model, provider, from, to, and mission_name; there is no limit, cursor, view, or run_ids argument. Example: (analysis/counters {"run_id" "cmd-..."}). Call once per selected run_id to reduce an explicit cohort.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-counters`

##### `analysis/open`

```clojure
(analysis/open run-id)
```

Opens one captured run and returns its available evidence collections.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-open`

##### `analysis/read`

```clojure
(analysis/read run-id options)
```

Reads one bounded page from a captured run-evidence collection. Put collection, limit, cursor, and the selected collection's advertised filters directly in options; do not nest them under filters. Call analysis/open first to discover the accepted filters for each collection.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-read`

##### `analysis/runs`

```clojure
(analysis/runs options)
```

Lists captured runs using the stable run-analysis profile.

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-runs`

### `debug.nav`

Typed navigation over one immutable private run-evidence capture. The mission must select its correlated inspection snapshot provider under the conventional alias debug.nav.

- **Visibility:** `prompt`
- **Direct dependencies:** `cap`
- **Selecting it also installs:** `cap`
- **Directly used by:** —

```json
{"library": "debug.nav"}
```

#### Public exports

##### `debug.nav/counters`

```clojure
(debug.nav/counters filters)
```

Return trace counters for a filtered run cohort, including adapter-attested model usage. Filters are the existing counter keys; call once per selected run_id to reduce an explicit cohort. Example: (debug.nav/counters {"run_id" "run-id"}).

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(filters :map) -> :map`
- **Backing requirements:** `tool:debug.nav.counters`

##### `debug.nav/follow`

```clojure
(debug.nav/follow run-id relationship options)
```

Follow one typed relationship returned by an evidence item. The relationship supplies the exact target collection and filters; options may contain only limit and cursor. Check the relationship first: one whose state is "unavailable", or whose filters are null, cannot be followed and calling follow on it fails the program instead of returning a page. Returns the original relationship beside the complete native page envelope. Example: (debug.nav/follow run-id relationship {"limit" 20}).

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string, relationship :map, options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.read`

##### `debug.nav/open`

```clojure
(debug.nav/open run-id)
```

Open a run and discover available collections, filters, identifiers, and completeness fields. Example: (debug.nav/open "run-id").

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string) -> :map`
- **Backing requirements:** `tool:debug.nav.open`

##### `debug.nav/read`

```clojure
(debug.nav/read run-id options)
```

Read one native evidence page. Put collection and advertised filters directly in options; do not nest them under filters. Example: (debug.nav/read "run-id" {"collection" "turns" "evaluation_id" "mission-evaluation-9"}).

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string, options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.read`

##### `debug.nav/runs`

```clojure
(debug.nav/runs options)
```

List captured runs. Example: (debug.nav/runs {"status" "error" "limit" 5}).

- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.runs`

### `prompt.audit`

Size measurement for a rendered agent system prompt.

`agent.prompt/render` interleaves authored instruction text with
manifest-derived API text, so one byte count for the whole prompt cannot say
which of the two an edit moved. These functions take the rendered string —
from a recorded run, a committed fixture, or any other source — and answer
three questions about it: which segments it is made of, how large each one is,
and what changed between two versions.

Every function is pure and takes a string. Nothing here reads a run, calls a
capability, or assembles a manifest, so the same numbers are available to a
REPL session reading recorded evidence and to a test guarding a fixture.

- **Visibility:** `discoverable`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** —

```json
{"library": "prompt.audit"}
```

#### Public exports

##### `prompt.audit/delta`

```clojure
(prompt.audit/delta before after)
```

Compares two rendered prompts and reports the character change per segment.

Returns {"rows" [...]}, one row per label present in either input, in the
emission order of `after` with labels unique to `before` appended. Each row is
{"label" .. "before" .. "after" .. "change" .. "percent" ..}.

All three counts are characters; `delta` reports no token estimates. A label
present on only one side counts 0 on the other. `percent` is the change
against `before` rounded to one decimal place, and nil when `before` is 0.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `prompt.audit/measure`

```clojure
(prompt.audit/measure text)
```

Measures a rendered agent system prompt, per segment and in total.

Returns {"rows" [...] "recognised?" bool}. `rows` holds one row per
present segment in emission order, then the derived rows `authored`,
`dynamic` and `total`. Each row is {"label" .. "characters" ..
"lines" .. "tokens_estimated" ..}.

`characters` is authoritative and counts graphemes, as `count` does. Bytes
are not reported: the string surface exposes no UTF-8 byte size, and
characters are tokenizer-independent and sufficient for a budget.
`tokens_estimated` is ceil(characters / 4) — an estimate, named so a caller
cannot mistake it for a measurement — and the derived rows compute it from
their own aggregated character count rather than by summing per-segment
estimates, which would differ.

`authored` sums the fixed prompt-policy segments. `dynamic` sums `api-notes`,
`api-entries`, and the manifest-driven result and phase contract projections;
an `unrecognised` segment counts as authored. So
authored + dynamic equals total in both cases. Treat the split as approximate
reporting: the dynamic segments carry authored formatter text — headings and
the per-entry `Call`, `Type` and `Docs` labels — so it
says roughly how much of a rendering a manifest drove, and no more. A budget
reads `total`.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

##### `prompt.audit/segments`

```clojure
(prompt.audit/segments text)
```

Splits a rendered agent system prompt into its ordered emission segments.

Returns a vector of {"label" .. "text" ..} in the order `render` emits
them: marker, protocol, language, examples, api-heading, api-notes,
api-legend, api-entries, result-contract, phase-return-contract. Each label
occurs at most once. `api-notes`, `api-entries`, and both optional contract
projections are manifest-derived; the remaining segments are authored in
`agent.prompt`. The order is the structure — the rendering interleaves
authored and dynamic text, so no unordered value can encode reassembly.

The authored empty-API sentence is an `api-empty` segment. `api-notes` is absent
when the mission declares no namespace docstrings. Result and phase-return
contracts are optional dynamic suffix segments.

Recognition validates the V1 marker, boundary anchors, their ordering and
uniqueness, complete entry termination, and the fixed contract prefixes. It
is structural rather than a byte-for-byte validation of authored prose. A
string that fails those checks returns one `unrecognised` segment carrying
the whole input instead of guessed boundaries.

Joining the segment texts in order reproduces the input exactly, in both the
recognised and the unrecognised case. That invariant is what makes the
per-segment character counts add up to the whole.

- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —

## Related guides

- [Components and preludes](guides/components-and-preludes.md) explains local components, contracts, dependency boundaries, and authority.
- [Building agents](guides/building-agents.md) applies the agent libraries to workflow and mission design.
- [Agent library reference](agent-library-reference.md) defines the complete loop configuration, turn protocol, retry, and failure behavior.
- [Manifests and capabilities](guides/manifests-and-capabilities.md) defines selection and environment assembly.