base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Record proposed CLI decisions and clarify CommandKit boundaries

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 23:36:06 +00:00
parent 6a0467148e
commit 84234275eb
15 changed files with 1243 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/adr/0008-inspection-lifecycle.md Normal file
View File

@@ -0,0 +1,114 @@
# 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.