# Adapter And Repository Internals

## Purpose

This document describes implemented adapter/repository boundaries and their current behavior.

## Adapter Map

- `internal/adapter/cli`: CLI command parsing, app wiring, stdout/stderr handling, exit codes.
- `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
- `internal/promptdef`: filesystem prompt-definition repository.
- `internal/profile`: filesystem execution-profile repository.
- `internal/artifact`: input artifact reader.
- `internal/prompt`: Go-template renderer.
- `internal/llm`: OpenAI-compatible LLM client implementation.
- `internal/validate`: output validator.
- `internal/format`: prepared-run formatters for `render` output.

## Inputs And Outputs

CLI adapter:

- Input: process args, filesystem config/assets, environment.
- Output: exit code, stdout artifact/prepared output, stderr summaries/errors.

HTTP adapter:

- Input: JSON request body (`runRequestDTO`).
- Output: JSON success/error body with mapped status codes.

Filesystem repositories:

- Input: prompt/profile YAML files.
- Output: normalized domain definitions/profiles or typed errors.

Artifact reader:

- Input: `domain.ArtifactRef`.
- Output: loaded `domain.Artifact`.

LLM adapter:

- Input: `domain.GenerateRequest`.
- Output: `domain.GenerateResponse`.

Validator:

- Input: artifact body + output contract.
- Output: validation result or runtime validation error.

## Boundaries

- Adapters convert external representations to domain requests and back.
- Use-case decisions remain in `internal/usecase`.
- External dependency details stay scoped to adapter packages.

## Config Fields Used

Primary app settings consumed by adapters:

- `prompt_dir`
- `profile_dir`
- `schema_dir`
- `server.addr`
- `defaults.render_format`

Execution profile/request settings used through runner:

- `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `api_key_env`, `reasoning_effort`, `extra_params`

## External Dependencies

- YAML decoding: `gopkg.in/yaml.v3` (strict known-fields mode in config/prompt/profile loaders).
- JSON Schema validation: `github.com/santhosh-tekuri/jsonschema/v6`.
- HTTP client/server: Go standard library.

## Failure Behavior

Strict decoding and input checks:

- config/prompt/profile loaders reject unknown YAML fields.
- HTTP DTO decoder rejects unknown JSON fields.
- raw API key payload fields are rejected by strict decoding in profile/http paths.

Artifact refs:

- Supported reference types: `inline`, `file`.
- Unsupported types return `ErrUnsupportedRefType`.

LLM adapter:

- endpoint appends `/chat/completions`.
- non-2xx responses map to request failure errors.
- malformed responses (including missing/empty first choice content) are errors.

Validator:

- `basic`, `json`, `json_schema` content failures return `ValidationFailed` results.
- schema load/compile/path failures are runtime errors.

HTTP error mapping:

- maps domain/use-case errors to stable HTTP code + error code/message.
- avoids returning internal wrapped-cause details in response payload.

## CLI Adapter Semantics

Implemented commands:

- `run`
- `render`
- `serve`

Behavior highlights:

- `run` exit `2` indicates validation failed after generation.
- `render` does not call the LLM.
- `serve` exposes HTTP handler only; no built-in auth.
- `render` supports `--format text|json`; `render` does not expose `--schema-dir`.
- deprecated aliases `--prompt-id` and `--profile-id` are still accepted.

## Tests To Inspect Before Changing

- `internal/adapter/cli/run_test.go`
- `internal/adapter/http/handler_test.go`
- `internal/promptdef/repository_test.go`
- `internal/profile/repository_test.go`
- `internal/artifact/reader_test.go`
- `internal/prompt/renderer_test.go`
- `internal/llm/openai_compatible_client_test.go`
- `internal/validate/standard_validator_test.go`
- `internal/format/prepared_run_test.go`

## Architectural Invariants

- Adapter packages do not own runner decision logic.
- External request/response strictness is part of contract stability.
- Prepared-render output never includes resolved API key values.
- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `response_format`).