Files
scriptorium/docs/internal/adapters.md

4.9 KiB

Adapter Internals

Adapters map executable inputs and effects through public upstream values. The CLI, HTTP API, and architecture policy own their external contracts and boundaries.

CLI Composition And Acquisition

app.go composes application run/serve declarations with native configuration, PromptKit, completion, help, and version support. CommandKit owns parsing, declaration-input checks, reporting selection, presentation, and finalization.

selection.go maps explicit native config/overlay choices and server-only HTTP bindings into internal/config.Load. It preserves supplied empty/zero values. Native application --set records remain upstream records with native conflict handling. No application selectors are installed under configuration commands.

native_config.go adapts the actual application result through ckconfig.FromConfigKit and framework inspection through ckprompt.ConfigScope. Native views own effective values, paths, metadata, sources, findings, explanations, redaction, and comparison. Application inspection does not construct an engine. Comparison loads each side from that side's selection; there is no config/engine cache or effective-document reconstruction.

acquisitionState contains application diagnostic evidence only, never loaded configuration or engines. Callback decorators forward it through native Acquired channels. An application LoadError is transported separately while the framework adapter runs, then its original typed cause is restored before native outcome classification. This prevents app findings from becoming framework findings. Native framework evidence remains unchanged; comparison application messages identify left/right context. Callback marks prevent replay when operations share invocation state.

native_prompt.go installs all twelve ckprompt callbacks, nil request builders, and empty-default native namespace views. Inventories, named resources, requirements, validation, preparation, and smoke testing retain their upstream lifecycles and reports.

Generation And Delivery

native_run.go binds the required operand and reusable resource/input/execution flags into a native RunRequest. Ordinary typed namespace flags feed Engine.WithNamespaces; stored references are not rewritten. One Engine.Run call receives the invocation context and unchanged operation duration. PromptKit owns preparation, credentials, admission, retries, repairs, and content validation.

outcomes.go maps typed failures and native configuration evidence to native outcomes, preserving causes while keeping provider payloads out of terminal explanations. A returned completed validation failure remains a domain outcome; an unexpected nil successful result is an integration failure.

delivery.go submits the actual RunResult to the invocation reporter with a reusable artifact-byte text template. The optional file renders that same value without the template through CommandKit's writer API, outside reporter callbacks to avoid reentrancy. File failures add explanations/causes while reporter presentation failures remain native. See delivery semantics.

Server And HTTP

server.go loads application settings, injects the restricted artifact reader into one engine, installs the existing HTTP handler/limits, and opens a listener. It retains the header timeout and engine retry defaults. Context cancellation calls Server.Close; callback coordination finishes connection/listener closing before return, without waiting for arbitrary context-ignoring application work.

The HTTP handler strictly decodes DTOs and applies transport policy before mapping to PromptKit requests. Its Runner interface is a consumer-side external boundary using native values. Request controls do not mutate shared engine defaults; shared backend capacity accounting remains in that engine.

HTTP optional reports use one per-request internal/report.Collector, attached only for opted-in requests. It copies terminal aggregates, not event history, and is never the CLI result report. Success/error attachment and encoded-size handling retain the HTTP contract. Reader sentinel identities survive PromptKit wrapping for status mapping.

Verification

Native composition/configuration/prompt/run/delivery/lifecycle tests protect the application's integration choices using real libraries and controlled local providers. Checkout-discovery tests cover fresh invocations and entry-file spellings. Entrypoint tests protect identity/status mapping; HTTP reader/DTO/ report/capacity regressions and the architecture guard remain their own owners. Do not duplicate upstream parsers, analyzers, serializers, or exhaustive format matrices to change an adapter.

When changing behavior, update its canonical external contract and focused integration protection. Required shared capabilities belong upstream before tagged adoption, not in a resurrected application framework facade.