scriptorium/docs/internal/adapters.md

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 and HTTP API reference. Promptkit's public engine contract is described by its tagged Go consumer guide.

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 when application source locations or HTTP artifact containment changes.