# Scriptorium Adapter Internals

This document describes the subprocess adapter in
`internal/adapters/scriptorium`.

## Purpose

The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
for Markdown report generation. It isolates subprocess execution, argv
construction, timeout handling, output capture, and exit-code interpretation
from app and domain packages.

## Inputs And Outputs

Inputs:

- prompt ID
- prompt input data package path
- report output path for `run`
- configured binary, config path, profile, timeout, and extra arguments
- context for cancellation

Outputs:

- argv used for execution
- captured stdout and stderr
- truncation flags for captured output
- exit code
- report output path for `run`

## Boundaries

`internal/adapters/scriptorium` owns Scriptorium command construction and
subprocess execution. It does not choose report types, build prompt input,
fetch weather data, decide workflow order, or persist workflow metadata.

The adapter exposes request and result structs for render and run operations.
State persistence uses a state-owned preflight artifact shape; app
orchestration converts render results before saving.

## Config Fields Used

- `scriptorium.binary`
- `scriptorium.config_path`
- `scriptorium.profile`
- `scriptorium.timeout`
- `scriptorium.extra_args`

## Commands

Render preflight argv starts with:

```text
scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
```

Report generation argv starts with:

```text
scriptorium run --prompt <prompt_id> --input data_package=<path> --out <path>
```

Configured `--config` and `--profile` flags are inserted after the subcommand
and before prompt-specific arguments. Extra arguments are appended after the
built-in arguments.

## Execution Behavior

The adapter runs commands without shell interpolation. The same private
execution path is used by render and run after command-specific request
validation and argv construction.

When `scriptorium.timeout` is greater than zero, each subprocess call uses a
context with that timeout. Stdout and stderr are captured separately, capped at
1 MiB each, and marked as truncated when the cap is reached.

## Failure Behavior

- Missing prompt ID or data package path returns an error before subprocess
  execution.
- Missing run output path returns an error before subprocess execution.
- Subprocess start errors, context cancellation, and timeouts are wrapped with
  operation context by the caller-facing method.
- Nonzero render and run exits return the captured result plus an error
  containing the exit code and stderr.

## Tests

Inspect:

- `internal/adapters/scriptorium/runner_test.go`
- `internal/app/app_test.go`
- `internal/cli/root_test.go`

## Invariants

- No shell interpolation is used.
- The Scriptorium input name is `data_package`.
- Render and run preserve command-specific result structs.
- Scriptorium-specific flags stay inside adapter and config boundaries.