Record ConfigKit adoption scope and deferred inspection work
This commit is contained in:
@@ -1,9 +1,9 @@
|
||||
# ConfigKit v1.1.0 adoption
|
||||
|
||||
Status: proposed; dependency and report changes are not implemented. This
|
||||
roadmap covers the embedded `ckconfig` integration, the API coverage review,
|
||||
and recommended extensions. Release coordination and capability scope have
|
||||
recommendations under [Open Decisions](#open-decisions).
|
||||
Status: recommended adoption scope recorded; implementation has not begun.
|
||||
This roadmap covers the embedded `ckconfig` dependency and source-report
|
||||
migration. [Recommended scope decisions](#recommended-scope-decisions) record
|
||||
the first sprint and the extensions deferred to later work.
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
@@ -138,40 +138,20 @@ link to the owning inspection contract for their semantics. Describe the report
|
||||
migration plainly in the release note. The target uses the new field names
|
||||
without duplicate legacy report fields.
|
||||
|
||||
ConfigKit's source inventory also supplies `EmptyImportSelections`, with
|
||||
declaration path, location, and selector. OD-2 addresses including this evidence
|
||||
in the existing source report; it is not yet a selected report-schema addition.
|
||||
Include `EmptyImportSelections` as `empty_import_selections` in both text and
|
||||
YAML source reports under OD-2. Project each declaration path, location, and
|
||||
native selector in the returned record order. Emit `empty_import_selections: []`
|
||||
when there are no records. These are planned report changes; update the owning
|
||||
CLI contract when implemented.
|
||||
|
||||
### Recommended inspection expansion
|
||||
### Deferred inspection expansion
|
||||
|
||||
After the dependency and source-report adoption, prioritize an optional
|
||||
metadata capability for field inspection, path discovery, and provenance
|
||||
history. A narrow provider facet could expose ConfigKit's public `Metadata`
|
||||
value directly. `FromConfigKit` can supply it from the loaded result; custom
|
||||
scopes can declare the operations for which they provide the capability.
|
||||
This is a proposed extension, not a new requirement on existing providers.
|
||||
|
||||
Use upstream `Lookup` and `IsExplicit` for effective field metadata,
|
||||
`HistoricalPaths` for observed-path enumeration, and `History` for definition,
|
||||
inheritance, and resolution records. `HistoricalPaths` includes effective and
|
||||
removed paths; it is not simply a list of current fields. Scope the report to
|
||||
the returned upstream evidence rather than inferring an independent provenance
|
||||
model. Command names, selectors, and report shapes need a focused design once
|
||||
this extension is selected; this roadmap does not establish their grammar.
|
||||
|
||||
Field-origin inventories are currently among the
|
||||
[deferred proposals](deferred.md#other-deferred-proposals). OD-3 proposes
|
||||
reconsidering that scope based on the reviewed public API. If selected, update
|
||||
that record and the owning CLI/API documentation with implementation. Retaining
|
||||
the proposal here does not by itself mark the extension accepted or implemented.
|
||||
|
||||
Failed-load source inspection, detailed comparison reports, and structured
|
||||
diagnostics remain separately considered additions under OD-4 through OD-6.
|
||||
They use existing upstream evidence, but each changes CommandKit's presentation
|
||||
or outcome coordination and needs its own scope choice. In particular, source
|
||||
inventory output on an acquisition error would retain the failed outcome;
|
||||
additional comparison detail would expose the native left/right snapshots,
|
||||
presence/redaction fields, and `HiddenChanged` already returned to the provider.
|
||||
Metadata inspection and path discovery are recommended as the next functional
|
||||
sprint after adoption (OD-3). Failed-load source inventory, detailed comparison,
|
||||
and structured diagnostics remain separate later proposals (OD-4 through OD-6).
|
||||
The [configuration inspection extensions](deferred.md#configuration-inspection-extensions)
|
||||
record owns their proposed capabilities and design considerations. None is part
|
||||
of this adoption sprint or a new requirement on existing providers.
|
||||
|
||||
### Consumer migration and module coordination
|
||||
|
||||
@@ -192,54 +172,72 @@ compatibility loader or impose new configuration restrictions.
|
||||
ckprompt's current ConfigKit types come from the old package identity. It cannot
|
||||
simply select the new ckconfig release while retaining that wiring. Its later
|
||||
adoption needs a coordinated ConfigKit/PromptKit migration and review of its
|
||||
own adapters and composed example. OD-1 determines scheduling; this roadmap does
|
||||
not select an unreviewed PromptKit release or claim a new matched integration set.
|
||||
own adapters and composed example. Under OD-1, prepare ckconfig independently
|
||||
first and review ckprompt next. This roadmap does not select an unreviewed
|
||||
PromptKit release or claim a new matched integration set.
|
||||
|
||||
### Interim workspace guidance
|
||||
|
||||
Once local ckconfig uses the vanity ConfigKit types, the usual three-module
|
||||
`go.work` selects it for local ckprompt as well. Until ckprompt migrates, its
|
||||
old-path ConfigKit inspection and comparison types cannot satisfy the new
|
||||
ckconfig contracts. This is a temporary composition mismatch, even though each
|
||||
module can be validated independently against its own dependencies.
|
||||
|
||||
During that interval, preserve the ignored local workspace and use `GOWORK=off`
|
||||
for dependency preparation, tests, and example runs. From the repository root,
|
||||
with the selected Go 1.27 toolchain on `PATH` and dependencies prepared:
|
||||
|
||||
```sh
|
||||
GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
|
||||
(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
|
||||
(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
|
||||
```
|
||||
|
||||
The unchanged ckprompt suite and composed example then use published ckconfig
|
||||
v0.2.0 and their existing upstream dependencies. Their success does not validate
|
||||
composition with the migrated local ckconfig. Keep local replacements and
|
||||
workspace files out of the adoption commit. Resume three-module workspace and
|
||||
composed-consumer validation after ckprompt's migration; update the ignored
|
||||
workspace's Go version as needed for its member modules at that point.
|
||||
|
||||
When the dependency change lands, update the development guide's workspace
|
||||
instructions to explain this interval. Restore the aligned-workspace guidance
|
||||
when ckprompt adopts the new dependencies. Until implementation, the existing
|
||||
development instructions describe the current compatible baseline.
|
||||
|
||||
## Work from the baseline
|
||||
|
||||
1. **Confirm scope choices and prepare module metadata.** Resolve OD-1 and
|
||||
OD-2 and record which proposed extensions, if any, join the adoption release.
|
||||
Deferred extensions need not block the dependency migration. Select the
|
||||
1. **Prepare module metadata for the recommended scope.** Follow OD-1 and
|
||||
OD-2; OD-3 through OD-6 remain deferred. Select the
|
||||
Go 1.27 maintainer toolchain, update ckconfig's requirement,
|
||||
imports, and minimum, and regenerate authentic sums with workspace discovery
|
||||
off. Inspect the resulting dependency graph; do not commit local replacements
|
||||
or environment files as an adoption mechanism.
|
||||
2. **Adapt APIs and source reports.** Update the native source field accesses,
|
||||
DTOs, text/YAML output, affected tests, and example code. Apply the selected
|
||||
empty-import-evidence choice. Preserve current coordination and outcomes
|
||||
except where an explicitly selected extension changes presentation, such as
|
||||
retaining a failure alongside returned source evidence. Adapt upstream
|
||||
results rather than adding domain validation.
|
||||
3. **Design and implement selected extensions.** Treat metadata inspection and
|
||||
path discovery as the next functional work item under OD-3, whether included
|
||||
here or scheduled next. Define its optional provider capability, CLI usage,
|
||||
and report projection together. For any OD-4 through OD-6 feature selected,
|
||||
specify its report delivery and outcome behavior before implementation.
|
||||
Reuse native records and rendering where suitable; avoid a second domain
|
||||
implementation or a generic framework solely to mirror upstream APIs.
|
||||
4. **Update canonical documentation and notices.** Revise the ckconfig README
|
||||
DTOs, text/YAML output, affected tests, and example code. Add empty-import
|
||||
evidence, including empty lists and record order. Preserve
|
||||
current coordination and outcomes. Adapt upstream results rather than
|
||||
adding domain validation.
|
||||
3. **Update canonical documentation and notices.** Revise the ckconfig README
|
||||
and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources),
|
||||
consumer guide, and release toolchain instructions with the implemented
|
||||
changes. Review the selected graph and upstream notices, then update
|
||||
ckconfig attribution with the vanity identity, selected versions, and pinned
|
||||
source links. Update other module notices only when their actual selections
|
||||
consumer guide, release toolchain instructions, and development workspace
|
||||
guidance with the implemented changes. Review the selected graph and
|
||||
upstream notices, then update ckconfig attribution with the vanity identity,
|
||||
selected versions, and pinned source links. Update other module notices only when their actual selections
|
||||
change. Preserve published release history.
|
||||
5. **Validate the selected end state.** Run the ckconfig suite, including its
|
||||
4. **Validate the selected end state.** Run the ckconfig suite, including its
|
||||
maintained example, independently with `GOWORK=off` and read-only module
|
||||
metadata on the selected Go 1.27 toolchain. Update focused adapter/report
|
||||
assertions for the new vocabulary and faithful projection of returned
|
||||
evidence. Preserve coverage of request forwarding, diagnostics, cancellation,
|
||||
output failures, and supported error identity. Assertions establish
|
||||
CommandKit adaptation; ConfigKit owns tests of its domain correctness.
|
||||
For selected metadata capabilities, verify query forwarding and returned
|
||||
field/history projection. For failed-load inventory or detailed comparison,
|
||||
verify the selected report and outcome coordination without re-establishing
|
||||
upstream acquisition, provenance matching, or sensitivity behavior.
|
||||
Review changed Markdown links, fragments, and examples. If coordinated
|
||||
ckprompt work is selected, also validate that module and the composed consumer
|
||||
against the proposed dependency set; local-workspace success alone does not
|
||||
establish independent module compatibility.
|
||||
6. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the
|
||||
Review changed Markdown links, fragments, and examples. Use the interim
|
||||
workspace guidance for unchanged modules; record that their independent
|
||||
checks do not establish compatibility with the migrated ckconfig. Full
|
||||
composed-workspace validation belongs to the later ckprompt migration.
|
||||
5. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the
|
||||
existing fresh-version guards, with tag `integrations/ckconfig/v0.3.0`.
|
||||
Explain changed ConfigKit type identity, Go minimum, report fields, and
|
||||
consumer migration in its checked-in note with the usual licensing footer.
|
||||
@@ -254,107 +252,35 @@ Implementation is complete when ckconfig's actual module metadata and imports
|
||||
select the new dependency, the selected report changes faithfully expose its
|
||||
returned evidence, the module suite and maintained consumer pass independently,
|
||||
and current documentation, notices, and release preparation describe that state.
|
||||
Record resolved scope choices, final validation evidence, and the status of
|
||||
each proposed extension. Features selected for this implementation need their
|
||||
own provider/report evidence; recording a deferred proposal does not demonstrate
|
||||
its implementation. A future source release is reported separately from
|
||||
implementation completion; preparing this roadmap does not publish a version
|
||||
Record final validation evidence and the temporary workspace composition
|
||||
status. OD-3 through OD-6 remain in deferred work; their implementation is not
|
||||
a completion condition for this sprint. A future source release is reported
|
||||
separately from implementation completion; preparing this roadmap does not publish a version
|
||||
or migrate external applications.
|
||||
|
||||
## Open Decisions
|
||||
## Recommended scope decisions
|
||||
|
||||
### OD-1: Release ckconfig first or coordinate both integrations?
|
||||
These dispositions record the review recommendations for the adoption sprint.
|
||||
They define its planned scope, not implemented contracts or authorization to
|
||||
publish. Deferred features still need focused API and CLI design.
|
||||
|
||||
**Recommendation:** implement and release ckconfig independently first, and
|
||||
review ckprompt's upstream migration as the next integration task. This keeps
|
||||
the current scope concrete and uses the established independent module releases.
|
||||
Existing ckprompt v0.2.0 consumers retain their published dependency set; document
|
||||
that moving them to the new ckconfig needs the corresponding ckprompt migration.
|
||||
The tradeoff is an interval with no newly aligned release pair.
|
||||
| Decision | Recommended disposition | Reason |
|
||||
| --- | --- | --- |
|
||||
| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep this sprint focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. |
|
||||
| OD-2: Empty-import evidence | Include `empty_import_selections`, with `[]` when empty, in text and YAML source reports. | Exposes existing upstream evidence alongside the other report-schema changes. |
|
||||
| OD-3: Metadata and path discovery | Defer to the next functional sprint after adoption. | A coherent optional capability needs its own field/history report and command design. |
|
||||
| OD-4: Failed-load source inventory | Defer to a separate source-inspection enhancement. | Requires source evidence on error and deliberate report/failure coordination. |
|
||||
| OD-5: Detailed comparison | Defer; retain the existing reduced report in this sprint. | A richer form needs a report-selection and compatibility decision. |
|
||||
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering in this sprint. | Coordinate machine-readable records with shared reporting and outcome delivery. |
|
||||
|
||||
**Viable alternative:** complete the ConfigKit/PromptKit review and both
|
||||
integration migrations before releasing the next pair, publishing ckconfig first
|
||||
in dependency order. This gives composed consumers a coordinated adoption path
|
||||
and validates the shared type boundaries together. It expands this work into
|
||||
PromptKit adoption and delays ckconfig availability while that review and
|
||||
implementation proceed. No simultaneous tag publication is needed.
|
||||
The first sprint therefore covers dependency and API migration, source-report
|
||||
terminology and empty-import evidence, documentation and notices, independent
|
||||
module validation, and ckconfig release preparation. Core retains its own Go
|
||||
minimum. Application loaders continue to own discovery and loading policy.
|
||||
|
||||
### OD-2: Include empty-import-selection evidence in this adoption?
|
||||
|
||||
**Recommendation:** add `empty_import_selections` to the existing text/YAML
|
||||
source report, projecting ConfigKit's declaration path, location, selector, and
|
||||
record order. This exposes structured source evidence already available
|
||||
upstream without a new command or a second explanation engine. It adds report
|
||||
mapping and focused projection coverage alongside the other schema changes;
|
||||
the exact empty-list presentation should be settled with the implemented report.
|
||||
|
||||
**Viable alternative:** limit this release to migrating the evidence already
|
||||
reported, and defer this additive field to a later inspection enhancement. That
|
||||
reduces the immediate report change and test scope, and still makes the native
|
||||
metadata available to Go consumers of ConfigKit. CLI consumers would continue
|
||||
to lack this upstream evidence, and a later release would need another report
|
||||
and documentation update.
|
||||
|
||||
### OD-3: When and how should metadata inspection and path discovery land?
|
||||
|
||||
**Recommendation:** make optional metadata inspection and path discovery the
|
||||
next functional expansion after adoption. Expose the upstream metadata queries
|
||||
through an optional facet, and design field and history reports together. This
|
||||
adds explicitness, path discovery, and provenance information that current
|
||||
explanations do not fully expose, while keeping existing providers usable.
|
||||
It requires a focused CLI/API design and a later release if staged separately.
|
||||
|
||||
**Viable alternative:** include that coherent expansion in the adoption release.
|
||||
This gives consumers the broader inspection surface with one migration and
|
||||
documentation update. It increases the current release's API, report, and
|
||||
validation scope and can delay the dependency upgrade. Either schedule can use
|
||||
the same upstream-owned query semantics; final command grammar remains a design
|
||||
choice rather than a contract selected by this roadmap.
|
||||
|
||||
### OD-4: Expose acquired sources when a configuration load fails?
|
||||
|
||||
**Recommendation:** evaluate this as a separate source-inspection enhancement,
|
||||
presenting `LoadError`'s returned inventory while retaining the load failure and
|
||||
diagnostics. It makes upstream acquisition evidence available for troubleshooting
|
||||
without treating the operation as successful. The design must account for
|
||||
returning the source facet on error and delivering a report before terminal
|
||||
failure presentation; that coordination is additional to mechanical adoption.
|
||||
|
||||
**Viable alternative:** include this behavior in the adoption release alongside
|
||||
the source-report changes. It delivers successful and failed-load inventory
|
||||
inspection together and avoids another source-report release. It broadens the
|
||||
current adapter and outcome changes and requires focused coverage of report
|
||||
delivery failures as well as acquisition failure. Retaining current diagnostic
|
||||
context alone until that work is selected remains viable.
|
||||
|
||||
### OD-5: Add a detailed native comparison report?
|
||||
|
||||
**Recommendation:** consider an additional report form in a later comparison
|
||||
enhancement, retaining the current reduced form for its established operator
|
||||
use. The detailed form would project `Path`, both snapshots, and `HiddenChanged`
|
||||
from native records, making already-returned evidence available to CLI consumers.
|
||||
Supporting two forms adds selection, presentation, and documentation work;
|
||||
choose the interface when the feature is selected.
|
||||
|
||||
**Viable alternative:** replace the reduced report with native-record projection
|
||||
in a pre-v1 minor release. One report form is simpler to maintain and exposes
|
||||
all current comparison fields directly. It requires deliberate migration of
|
||||
published report consumers and changes the concise additions/changes/deletions
|
||||
workflow. Keeping only the current form is also viable when that workflow meets
|
||||
consumer needs; richer reporting is a capability proposal, not a correctness fix.
|
||||
|
||||
### OD-6: Where should structured diagnostic reporting be introduced?
|
||||
|
||||
**Recommendation:** retain native diagnostic rendering for this adoption and
|
||||
consider structured records with CommandKit's shared reporting design. That
|
||||
keeps result and diagnostic delivery consistent across integrations and custom
|
||||
commands. It defers machine-readable native codes, paths, severities, and
|
||||
locations until their report channel and outcome behavior are designed.
|
||||
|
||||
**Viable alternative:** add an optional ckconfig-specific diagnostic report that
|
||||
projects ConfigKit's records directly. This could deliver useful structured
|
||||
evidence sooner without redesigning the shared reporting API. It introduces a
|
||||
separate presentation path whose interaction with ordinary results, warnings,
|
||||
and terminal failures needs definition and may later need alignment with other
|
||||
families. It is a lower-priority extension rather than a dependency-adoption
|
||||
requirement.
|
||||
Coordinating both integrations before release remains an alternative if a
|
||||
matched adoption path becomes necessary. It would expand the sprint to include
|
||||
PromptKit review and ckprompt migration; publication would still proceed in
|
||||
dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions)
|
||||
retains the capability proposals and unresolved design choices for OD-3 through
|
||||
OD-6, plus the possible source-ID filter.
|
||||
|
||||
@@ -25,6 +25,50 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only
|
||||
for a concrete consumer need and a deliberate API/behavior decision under the
|
||||
relevant ADRs.
|
||||
|
||||
### Configuration inspection extensions
|
||||
|
||||
The [ConfigKit v1.1.0 adoption review](configkit-v1.1.0.md#recommended-scope-decisions)
|
||||
recommends the following work after dependency and source-report adoption.
|
||||
Metadata inspection is the recommended next functional sprint; the other
|
||||
features have no selected sequence or delivery date. These proposals do not
|
||||
establish command grammar, report schemas, or new provider requirements.
|
||||
ConfigKit's public APIs own the evidence and its semantics.
|
||||
|
||||
- **Optional field metadata, path discovery, and history (OD-3).** Expose native
|
||||
`Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an
|
||||
optional provider capability. Design field and history reports together,
|
||||
keeping existing providers usable. Distinguish effective paths from removed
|
||||
historical paths: a failed `Lookup` must not suppress available `History`.
|
||||
Validate that distinction and faithful projection of returned field/change
|
||||
records without recreating upstream provenance logic. Historical enumeration
|
||||
is not an exhaustive inventory of possible schema fields. This gives the
|
||||
earlier field-origin inventory proposal a concrete, upstream-backed scope;
|
||||
command names, selectors, and report shapes remain to be designed.
|
||||
- **Failed-load source inventory (OD-4).** Present acquired source evidence from
|
||||
`LoadError.Sources()` while retaining the failed outcome and diagnostics.
|
||||
Design how an adapter returns its source facet on error and how result output
|
||||
precedes terminal failure presentation. Cover acquisition and report-delivery
|
||||
failures together; current diagnostic context remains available meanwhile.
|
||||
- **Detailed comparison (OD-5).** Consider an additional form projecting native
|
||||
`Difference` paths, both snapshots, presence/redaction fields, and
|
||||
`HiddenChanged`. The adoption sprint retains the reduced
|
||||
additions/changes/deletions report. Decide later whether a detailed form
|
||||
complements it or replaces it through a deliberate compatibility change.
|
||||
- **Structured diagnostics (OD-6).** Consider machine-readable native codes,
|
||||
paths, severities, and locations alongside CommandKit's shared reporting
|
||||
design. Define result/diagnostic channels, warning and terminal-failure
|
||||
interaction, and delivery outcomes. A ckconfig-specific report remains an
|
||||
alternative, with its cross-family alignment considered explicitly.
|
||||
- **Source-ID filtering.** Consider selecting a record already available in the
|
||||
source inventory. Native `Source(id)` lookup is a convenience; this proposal
|
||||
need not introduce another command or require a lookup method from every
|
||||
custom source provider.
|
||||
|
||||
Discovery, import defaults, collection identities, and field-level resolution
|
||||
recording remain available through application loaders. Standard inspection of
|
||||
resource contexts or secrets-directory bootstrap has no immediate proposal;
|
||||
those capabilities primarily serve application loading and startup.
|
||||
|
||||
### Alias completion and discovery
|
||||
|
||||
The delivered [shell completion feature](../cli.md#shell-completion) provides
|
||||
@@ -47,8 +91,9 @@ operator or consumer need and an appropriate ownership/behavior decision:
|
||||
- JSON reports and output-file management or reloadable export.
|
||||
- Shell completion extensions, including alias discovery described above and
|
||||
dynamic discovery of configured or remote values.
|
||||
- Configuration mutation, generic value assignment, and exhaustive field-origin
|
||||
inventories.
|
||||
- Configuration mutation and generic value assignment. Field metadata and
|
||||
provenance inspection are scoped under
|
||||
[configuration inspection extensions](#configuration-inspection-extensions).
|
||||
- Credential diagnostics beyond PromptKit's native smoke checks and additional
|
||||
live provider probes.
|
||||
- Additional component identity registration and domain artifact catalogs.
|
||||
|
||||
Reference in New Issue
Block a user