scriptorium/docs/internal/runner.md

# Runner Internals

## Purpose

`internal/usecase.Runner` is the core use case orchestrator for prompt preparation and execution.

It owns request validation, prompt/profile resolution, runtime-parameter merge, artifact loading, prompt rendering, structured-output setup, LLM invocation, output validation, and result metadata.

## Inputs And Outputs

Primary input type:

- `domain.RunRequest`

Primary output types:

- `domain.PreparedRun` from `Prepare`
- `domain.RunResult` from `Run`

LLM boundary types:

- `domain.GenerateRequest`
- `domain.GenerateResponse`

## Boundaries

`Runner` coordinates the following interfaces:

- `promptdef.Repository`
- `profile.Repository`
- `artifact.Reader`
- `prompt.Renderer`
- `llm.Client`
- `validate.Validator`
- optional `usecase.OutputRepairer`

Transport concerns (CLI flags, HTTP DTO parsing, status-code mapping) stay outside runner.

## Config Fields Used

`Runner` does not read app config files directly.

It receives fully constructed repositories/readers/validators from adapters. Effective behavior depends on adapter wiring, including:

- prompt/profile directories
- schema base directory
- selected profile/runtime overrides in request

## External Adapters Used

`Runner` works with adapter implementations via interfaces. Current wiring from CLI/HTTP uses:

- filesystem prompt/profile repositories
- composite artifact reader
- Go-template prompt renderer
- OpenAI-compatible LLM client
- standard validator

## State And Resume Behavior

`Runner` is stateless across requests.

- No durable run-state storage.
- No built-in resume/skip checkpoints.
- Each `Run`/`Prepare` executes from request inputs and current repositories.

## Failure Behavior

Primary runner error classes:

- `ErrInvalidRequest`: invalid run request envelope.
- `ErrProfileRequired`: specific invalid-request reason when neither request `profile_id` nor prompt `default_profile` is available.
- `ErrAPIKeyEnvMissing`: specific invalid-request reason when `api_key_env` is set but the named environment variable is unset/empty.
- `ErrPromptLoad`: prompt-definition repository load failures.
- `ErrProfileLoad`: execution-profile repository load failures.
- `ErrArtifactLoad`: artifact read failures.
- `ErrPromptRender`: template render failures.
- `ErrLLMGenerate`: outbound model request failures.
- `ErrValidation`: validation runtime failures (including structured-output schema load/compile failures).

Reason sentinel behavior:

- `ErrProfileRequired` and `ErrAPIKeyEnvMissing` are wrapped with `ErrInvalidRequest`.
- Adapters can use `errors.Is` for stable reason mapping without matching runner prose.

Validation content failures are not run errors:

- `Run` can succeed with `Validation.Status == failed`.
- CLI maps this to exit code `2`.
- HTTP returns `200` with failed validation details.

## Prepare Flow

`Prepare` performs:

1. validate request basics (prompt ID present).
2. load prompt definition by ID/version.
3. select profile ID:
   - explicit request profile ID
   - prompt `default_profile`
   - otherwise return an invalid request with `ErrProfileRequired`
4. load execution profile.
5. merge effective runtime target:
   - built-in execution defaults
   - selected profile values
   - request overrides
   - request numeric overrides are presence-aware, so omitted values preserve the current effective value and explicit zero values override it
6. verify credentials when the effective target names `api_key_env`:
   - a request-scoped direct API key satisfies the credential requirement
   - otherwise a missing/empty env value returns an invalid request with `ErrAPIKeyEnvMissing`
   - only the environment-variable name is returned in public output; secret values are never returned
7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
8. read input artifacts.
9. render prompt messages, including any normalized message cache-control metadata.
10. compute prompt/input/render hashes and return `PreparedRun`.

`rendered_prompt_hash` includes cache-control metadata when present because it affects the outbound provider request. Prompts without cache control keep the role/content hash behavior.

`Prepare` does not call the LLM.

Runtime target notes:

- Profile `extra_params` and request `extra_params` carry JSON-compatible values through prepared output, run metadata, and `domain.GenerateRequest.Target`.
- The OpenAI-compatible client serializes non-empty `reasoning_effort` as a top-level provider request field.
- The OpenAI-compatible client flattens `extra_params` into provider-specific top-level JSON request fields.
- Empty `extra_params` keys, reserved outbound field names, and values that cannot be JSON-encoded fail before the provider request.
- Resolved API-key values are never serialized in prepared/run output, public results, logs, or HTTP responses.
- Public direct API-key values are carried only far enough to call the configured LLM client and are excluded from JSON/YAML serialization.

## Run Flow

`Run` performs:

1. generate run ID.
2. call `Prepare`.
3. call LLM with prepared messages/effective target/structured-output spec.
4. build output artifact content type from output format.
5. validate output.
6. optionally attempt bounded repair when repairer is injected and contract allows it.
7. return `RunResult` with artifact, raw output, validation, hashes, profile/model metadata, token/cache usage, and timestamps.

## Repair Hook Boundary

Repair attempts occur only when all are true:

- repairer is injected
- `repair_attempts > 0`
- validation status is `failed`
- validation mode is `json` or `json_schema`

Current production wiring boundary:

- CLI and HTTP adapters call `usecase.NewRunner(...)` (no repairer argument).
- Therefore normal CLI/HTTP execution does not perform repair attempts today.

## Tests To Inspect Before Changing

- `internal/usecase/runner_test.go`
- `internal/usecase/integration_test.go`
- `internal/adapter/cli/run_test.go`
- `internal/adapter/http/handler_test.go`

## Architectural Invariants

- `Run` reuses `Prepare`; prepare logic is not duplicated.
- Effective API-key environment-variable name may appear; resolved secret value must not.
- Structured-output schema document must load before LLM call for `json_schema` mode.
- Repair loops are bounded by `repair_attempts` and repairer presence.
- Runner stays transport-agnostic.