# Integration: Scriptorium

## Purpose
Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.

## Adapter Boundary
Interface:
- `scriptorium.Runner`
- methods:
  - `RunArtifact(ctx, RunArtifactRequest)`
  - `RenderArtifact(ctx, RenderArtifactRequest)`

Primary implementation:
- `internal/adapters/scriptorium/SubprocessRunner`

Execution modes:
- `scriptorium run`
- `scriptorium render`

## Request Contract
Both request types carry:
- binary/config/prompt/profile IDs;
- input map and vars map;
- output path;
- timeout;
- generated config + stdout/stderr log paths;
- optional API-key env var name;
- optional working directory.

## Result Contract
`ArtifactResult` returns:
- output/log/generated-config paths;
- exit code and duration;
- command mode (`run` or `render`);
- prompt/profile provenance;
- `ValidationFailed` marker;
- metadata map.

## Validation and Failure Semantics
Request validation fails for:
- missing binary, prompt id, or output path;
- non-positive timeout;
- empty input/var names;
- empty input path values;
- missing required credential env var when `APIKeyEnv` is set.

Run behavior:
- subprocess errors propagate with context;
- `run` exit code `2` is mapped to `ValidationFailed=true`;
- successful subprocess still fails if output file is missing or empty.

Render behavior:
- subprocess errors propagate;
- output file must exist and be non-empty.

## Deterministic Behavior
- input and var maps are sorted into deterministic `--input` and `--var` CLI args.
- generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
- adapter is stateless and does not own artifact-selection policy.

## Config Mapping
Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.

Maintained examples with Scriptorium config:
- `examples/pipeline.full.annotated.yml`
- `examples/pipeline.production.yml`