5.8 KiB
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 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. 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 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 and selection contract define related target and input behavior. Application execution remains outside these library decisions.