115 lines
5.8 KiB
Markdown
115 lines
5.8 KiB
Markdown
# ADR 0008: Coordinate inspection through provider-supplied captured views
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
Operators use inspection to understand effective configuration and definitions.
|
|
An owning library's captured view gives values, provenance, and definition
|
|
metadata a coherent source. Application callbacks provide acquisition and domain
|
|
resolution that CommandKit cannot independently implement or audit.
|
|
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes lazy registration and
|
|
the boundary between library contracts and application guidance. This decision
|
|
covers CommandKit's use of loaded views and its invocation-local coordination.
|
|
|
|
## Decision
|
|
|
|
### CommandKit behavior
|
|
|
|
CommandKit invokes the registered provider when an inspection operation needs
|
|
its data. Standard handlers consume the provider's captured inspection views
|
|
through supported public contracts. Effective display uses final values supplied
|
|
by that view; source inventory and explanation use its provenance; definition
|
|
operations use its catalogs and resolved targets.
|
|
|
|
CommandKit coordinates declared dependencies and reuses compatible provider
|
|
results within an invocation. It requests each distinct resolved selection once
|
|
through that coordination path. Semantic diff requests independently resolved
|
|
left and right captures under [ADR 0011](0011-semantic-configuration-diff.md).
|
|
Provider-internal loading remains outside this coordination boundary.
|
|
|
|
`config validate` invokes the registered validation capability for each selected
|
|
scope and propagates its result. The PromptKit integration requests its public
|
|
configuration-validation operation, whose intended coverage is all configured
|
|
definitions. CommandKit uses the upstream operation's documented semantics;
|
|
additional upstream capabilities are needed where the public API lacks that
|
|
coverage.
|
|
|
|
CommandKit's inspection handlers acquire views, query them, validate through the
|
|
registered capability, and write reports. Model execution, request preparation,
|
|
capacity admission, artifact production, and operational preflight are domain
|
|
handler responsibilities outside the standard inspection family.
|
|
|
|
Help, version, and scope discovery use registration metadata independently of
|
|
inspection capture. Construction and those metadata operations leave acquisition
|
|
callbacks uninvoked.
|
|
|
|
### Provider contract
|
|
|
|
An inspection provider supplies views with the semantics required by its declared
|
|
operation. For the ConfigKit and PromptKit integrations, CommandKit consumes their
|
|
supported public inspection results and native writers. It preserves supplied
|
|
presence, resolution, provenance, and confidentiality semantics.
|
|
|
|
The provider boundary communicates selection identity, declared dependencies,
|
|
applicable operations, loading failures, and acquisition diagnostics. Loading and
|
|
validation steps are those required to produce the owning API's inspection result.
|
|
CommandKit requires the corresponding result contract, while the callback's
|
|
internal organization remains application-owned.
|
|
|
|
Acquisition can read files, environment values, or credentials and can perform
|
|
application-selected bootstrap work. CommandKit propagates supplied diagnostics
|
|
under [ADR 0005](0005-invocation-outcomes.md) and exposes supplied requirements in
|
|
help. Its coordination contract governs its own calls; callbacks retain their own
|
|
effects. CommandKit's API offers acquisition and inspection hooks independently
|
|
of application runtime construction.
|
|
|
|
CommandKit integrations adopt upstream capabilities through supported public
|
|
APIs. Secret classification and native rendering follow those APIs. New catalog,
|
|
comparison, or profile inspection support is an integration dependency for its
|
|
respective operation.
|
|
|
|
### Recommended application practice
|
|
|
|
Sharing loading and domain-resolution code between inspection and execution is
|
|
recommended: equivalent inputs can then produce equivalent effective values and
|
|
provenance. Acquisition callbacks are best kept focused on producing those views,
|
|
with application work performed by execution handlers.
|
|
|
|
These recommendations describe useful consumer structure. Applications control
|
|
their execution pipeline, callback implementation, credential lifecycle, and
|
|
bootstrap policy. CommandKit's decisions govern the hooks it offers and how its
|
|
handlers use the results.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Render mutable runtime configuration structs | Gives direct access to application values. Captured provenance, presence, and resolution need additional synchronization. |
|
|
| Reparse effective YAML for catalogs and queries | Uses available serialized data. CommandKit assumes upstream schemas and reconstructs definition semantics. |
|
|
| Include operational preflight in standard inspection | Adds readiness information. Inspection acquires provider-execution and state-management responsibilities. |
|
|
| Prescribe one consumer loading implementation | Encourages equivalent reports and execution. CommandKit has no authority over arbitrary callback or application internals. |
|
|
| Promise credential-independent acquisition | Simplifies an operator expectation. Actual upstream and callback loading requirements may require credentials. |
|
|
|
|
## Consequences
|
|
|
|
CommandKit reports describe provider-supplied captured state and preserve its
|
|
supported semantics. Dependency coordination reduces repeated provider calls
|
|
within an invocation. Shared loading is available as integration guidance.
|
|
|
|
The API needs clear result ownership, callback lifetime, dependency identity,
|
|
and diagnostic delivery. Report accuracy depends on the registered provider's
|
|
contract. Acquisition requirements and effects remain visible as supplied
|
|
integration metadata.
|
|
|
|
The [scope model](0009-configuration-scopes.md) and
|
|
[selection contract](0010-configuration-selection.md) define related target and
|
|
input behavior. Application execution remains outside these library decisions.
|