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.