eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Complete the public facade adapter boundary

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 00:57:53 +00:00
parent 280916bf4a
commit 3c33b52b15
10 changed files with 159 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/internal/adapters.md
View File

@@ -2,9 +2,9 @@
## 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`.
Adapters translate external inputs into public engine requests and translate
public results or errors back to their interface. They own IO and presentation
mechanics; use-case decisions remain behind the root `scriptorium` facade.
External contracts are canonical in the [CLI reference](../cli.md), [HTTP API
reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
@@ -14,35 +14,37 @@ reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md
- `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.
`internal/config`, constructs the public engine, and owns process output
handling.
- `internal/adapter/http` decodes DTOs, maps them to public run requests,
calls its local public `Runner` interface, and maps public 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.
- `internal/format` formats public prepared runs for the CLI.
## 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.
The CLI resolves configuration before constructing the public engine. `run`
calls `Engine.Run` with a public request and `render` calls `Engine.Prepare`
with the same request mapping. `serve` constructs the HTTP-owned restricted
artifact reader, injects it with `WithArtifactReader`, passes the resulting
engine directly to the 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.
That presence is carried into `scriptorium.ExecutionTargetOverride`, allowing
the engine 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
minimal request shape. It maps DTO values to public 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 public result to the response DTO; on failure it uses `errors.Is` over
public framework errors and HTTP-local artifact-policy errors to choose the
public error mapping.
The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
and externally observable limit behavior.
@@ -57,10 +59,10 @@ set and keeps direct request API keys out of public results.
## Package-Local Guarantees
- Adapters do not embed runner orchestration or source-loading decisions.
- Adapters do not embed framework 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.
- CLI and HTTP consume the public engine without a repairer; a repairer remains
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
@@ -105,9 +107,10 @@ sufficiency guidance.
### 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`.
1. Define or reuse an adapter-local consumer interface with public facade
types when a test seam is needed.
2. Implement translation and IO behavior without moving framework decisions out
of the public engine.
3. Add focused mapping, parsing, and error-behavior tests.
4. Update this document and the affected public or integration contract. Update
[source internals](sources.md) when source-loading behavior changes.