# Adapter Internals

## Purpose

Scriptorium adapters translate executable inputs into Promptkit public requests
and translate Promptkit results or errors back to CLI or HTTP behavior. They
own IO and presentation mechanics, not framework decisions.

External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md).

## Components And Collaborators

- `cmd/scriptorium` passes process arguments and streams to
  `internal/adapter/cli`.
- `internal/adapter/cli` resolves settings through `internal/config`,
  constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
  and owns output files, summaries, and exit codes.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
  public values, calls its adapter-owned `Runner` interface, and maps results
  and errors to HTTP DTOs.
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
  or JSON.

## Wiring Flows

### CLI

`run` calls `promptkit.Engine.Run`; `render` calls
`promptkit.Engine.Prepare`. Both share request mapping for prompt/profile
selection, file inputs, variables, and presence-aware execution overrides.
Omitted framework settings remain zero values so Promptkit resolves its own
defaults.

`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
adapter's consumer-owned `Runner` interface, and starts the server.

### HTTP

The handler enforces transport limits and strict JSON decoding before mapping
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
validation, model, usage, and metadata values directly.

Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
errors preserve their identity through Promptkit's artifact-load boundary.

## Package-Local Guarantees

- Adapters contain no copied framework types or orchestration.
- Configuration is resolved before Promptkit engine construction.
- Explicit numeric overrides preserve presence, including zero.
- HTTP DTO and error mapping remains stable and transport-owned.
- Resolved secrets are not serialized or printed.
- No adapter creates durable run state.

## Verification

Inspect:

- `internal/adapter/cli/run_test.go`
- `internal/adapter/http/handler_test.go`
- `internal/adapter/http/artifact_reader_test.go`
- `internal/format/prepared_run_test.go`
- `internal/adapter/dependency_test.go`

The adapter tests protect parsing, configuration mapping, output, status
mapping, restricted artifacts, and representative real Promptkit-engine
workflows. The dependency test protects the repository boundary.

## Change Recipes

For a CLI or HTTP change:

1. identify the Scriptorium-owned external contract;
2. map through Promptkit public values without copying framework semantics;
3. add or update the narrow application-owned test;
4. update the canonical Scriptorium contract; and
5. coordinate and tag Promptkit first if a required public capability is
   genuinely absent.

Update [source internals](sources.md) when application source locations or HTTP
artifact containment changes.