90 lines
4.9 KiB
Markdown
90 lines
4.9 KiB
Markdown
# Adapter Internals
|
|
|
|
Adapters map executable inputs and effects through public upstream values.
|
|
The [CLI](../cli.md), [HTTP API](../api.md), and [architecture policy](../policy/architecture.md)
|
|
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](../cli.md#results-and-separate-reports).
|
|
|
|
## 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](../api.md#execution-report). 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.
|