scriptorium/docs/internal/adapters.md

Adapter Internals

Purpose

Adapters translate external inputs into domain requests, compose dependencies, and translate domain results or errors back to their interface. They own IO and presentation mechanics; use-case decisions remain in internal/usecase.

External contracts are canonical in the CLI reference, HTTP API reference, and Go package contract.

Components And Collaborators

• cmd/scriptorium passes process arguments and streams to internal/adapter/cli.
• internal/adapter/cli parses commands, resolves application settings through internal/config, constructs a runner, and owns process output handling.
• internal/adapter/http decodes DTOs, maps them to domain.RunRequest, calls a runner interface, and maps errors and results to HTTP DTOs.
• The root scriptorium package maps its public types and options to internal collaborators and maps selected internal errors to public sentinels.
• internal/format formats prepared runs for the CLI; internal/llm, internal/prompt, and source packages supply runner dependencies.

Wiring Flows

CLI

The CLI resolves configuration before constructing dependencies. run builds a runner with the ordinary composite artifact reader and invokes Runner.Run; render uses the same wiring and invokes Runner.Prepare; serve replaces the file reader with the restricted artifact reader, builds an HTTP handler, and starts the server.

Parser state records whether numeric runtime values were explicitly supplied. That presence is carried into domain.ExecutionTargetOverride, allowing the runner to distinguish omitted values from explicit zero overrides.

HTTP

The handler first enforces transport limits, strict JSON decoding, and the minimal request shape. It maps DTO values to domain types without deciding prompt selection, source behavior, or validation semantics. On success it maps the domain result to the response DTO; on failure it uses errors.Is over runner, source, artifact, and profile errors to choose the public error mapping.

The HTTP API reference owns the route, DTO schema, status codes, and externally observable limit behavior.

Public Go Facade

NewEngine applies public options, selects filesystem, fs.FS, single-file, or in-memory dependencies, and constructs a runner. The conversion functions copy maps and slices across the boundary so callers do not receive internal domain values. The facade maps selected internal errors to the public sentinel set and keeps direct request API keys out of public results.

Package-Local Guarantees

• Adapters do not embed runner orchestration or source-loading decisions.
• Configuration is resolved before adapter dependency composition.
• CLI and HTTP create runners without a repairer; a repairer is available only through explicit internal runner construction.
• DTO conversion preserves explicit numeric-override presence.
• Error mapping matches error identities, not error text.
• No adapter creates durable run state; caller-selected output files are not application state.

Failure And Verification Boundaries

Keep external error payloads concise, preserve strict external decoding, and do not serialize resolved secret values. Validation content failures remain result state; runtime failures remain errors for the relevant adapter to map.

Inspect focused tests when changing this area:

• internal/adapter/cli/run_test.go
• internal/adapter/http/handler_test.go
• engine_test.go
• internal/format/prepared_run_test.go

Run the affected adapter package tests and recheck the relevant canonical contract. The testing policy owns global test sufficiency guidance.

Change Recipes

Application Configuration Fields

1. Add the field to the relevant internal/config shape and default handling.
2. Parse and validate it, then preserve configuration and CLI-override precedence while wiring it through its consuming adapter.
3. Add focused configuration and adapter tests for parsing, mapping, and effective behavior.
4. Update the configuration contract and any affected external contract.

CLI Flags

1. Add the flag to the relevant parser in internal/adapter/cli/run.go.
2. Keep command scope and application-configuration precedence intentional.
3. Add or update parser and command tests in internal/adapter/cli/run_test.go.
4. Update the CLI contract and affected maintained examples.

Adapter Capabilities

1. Define or reuse the appropriate domain or use-case interface boundary.
2. Implement translation and IO behavior without moving use-case decisions out of internal/usecase.
3. Add focused mapping, parsing, and error-behavior tests.
4. Update this document and the affected public or integration contract. Update source internals when source-loading behavior changes.