Adopt focused ConfigKit inspection in configuration roadmap

This commit is contained in:
2026-11-21 03:39:11 +00:00
parent 649bb7dcf2
commit f80ec1c42c

View File

@@ -52,8 +52,9 @@ unchanged; the change does not promise successful correction.
**Accepted:** the application composes configuration once through ConfigKit and **Accepted:** the application composes configuration once through ConfigKit and
passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit
locates the fixed root-level `promptkit` section and consumes only that section, locates the fixed root-level `promptkit` section and consumes only that section
ignoring sibling application settings. The application does not extract, reshape, for engine construction, ignoring sibling application settings. Inspection uses
the focused reporting semantics below. The application does not extract, reshape,
serialize, or reload a PromptKit-specific view. Do not add a configurable mounting serialize, or reload a PromptKit-specific view. Do not add a configurable mounting
key. key.
@@ -88,7 +89,11 @@ profile selection, required-resource checks, or diagnostics policy.
### Narrow ConfigKit Addition And Library-Owned Wiring ### Narrow ConfigKit Addition And Library-Owned Wiring
Use ConfigKit's proposed public lookup: Adopt the proposed lookup and focused inspection capabilities in ConfigKit's
[typed value and inspection roadmap](../../../ConfigKit/docs/roadmap/result-value.md).
That roadmap records agreed scope, not implemented APIs. Confirm availability
before implementation; do not assume the current dependency supplies them.
The lookup is:
```go ```go
func (r *Result[T]) Value(path Path) (any, bool) func (r *Result[T]) Value(path Path) (any, bool)
@@ -145,6 +150,7 @@ type Configuration interface {
Value(configkit.Path) (any, bool) Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool) SourceContext(string) (configkit.ResourceContext, bool)
InspectSubtree(configkit.Path) (configkit.Inspection, bool)
} }
``` ```
@@ -152,6 +158,9 @@ It selects `Value(configkit.Keys("promptkit"))`, checks its type, and captures
resources using native metadata and source contexts. Effective field origins are resources using native metadata and source contexts. Effective field origins are
authoritative; do not recover a missing effective location from historical evidence. authoritative; do not recover a missing effective location from historical evidence.
A serialized section loaded again is not an equivalent handoff. A serialized section loaded again is not an equivalent handoff.
Retain the inspection view selected at `/promptkit` for configuration reporting.
This interface sketch is not final; planning must also specify how existing load
diagnostics are retained and forwarded.
Register desired bundled resources as ordinary underlays before composition; Register desired bundled resources as ordinary underlays before composition;
engine construction must not inject another configuration layer into an already engine construction must not inject another configuration layer into an already
@@ -205,36 +214,73 @@ own validation and ConfigKit's document/composition rules still apply to the
whole document. Migration guidance must explain that unmigrated resources are whole document. Migration guidance must explain that unmigrated resources are
not loaded and can therefore produce missing-resource errors when selected. not loaded and can therefore produce missing-resource errors when selected.
### Explicitly Deferred Capabilities ### Focused Configuration Inspection
**Scoped configuration inspection:** native section-scoped effective output, **Accepted:** preserve resource listing and inspection, and provide configuration
metadata/history, explanations, and comparison are outside this initial addition. reporting through ConfigKit's proposed non-generic `Inspection` view:
`Value` does not supply those capabilities or alter existing redacted inspection.
Resource inspection still describes PromptKit resources. Planning must state how
existing `InspectConfiguration` APIs are exposed on the new handoff path; do not
silently describe whole-application reports as component-scoped or introduce a
substantial local reporting framework to imitate the deferred feature. Resolve
any resulting public API availability/migration choice explicitly, without making
native scoped reporting a prerequisite for engine construction.
**Independent source-version policies:** different application and component ```go
header policies within one load are outside this initial addition. ConfigKit's inspection, ok := result.InspectSubtree(configkit.Keys("promptkit"))
existing shared-policy limitation remains. Planning must document a supported ```
PromptKit's `InspectConfiguration()` forwards the view's capabilities without
loading another configuration or rebuilding history, redaction, or comparison.
Both application-owned loading and standalone construction use this reporting
path. This replaces the earlier inspection deferral; independent source-version
policies remain deferred.
The view is a reporting focus, not an isolation or access-control boundary.
Accept ConfigKit's native behavior:
- Effective output renders the selected subtree without enclosing application
mappings, using frozen completed-load values and existing redaction, including
sensitivity inherited from ancestors. Later settings mutation does not change
that evidence.
- Focused enumeration includes paths at or beneath `/promptkit`. Metadata remains
unfiltered, and explicit explanation/history queries use native application
paths and may query outside the focus. Do not rebase paths or add a separate
restriction layer.
- Sources and contextual evidence remain native and may describe other application
settings. Do not assign exclusive source ownership or trim ancestor history and
dependency evidence to manufacture an isolated report.
- Comparison uses ConfigKit's existing frozen-configuration comparison and retains
differences at, beneath, or above the focus. Sibling-only difference records are
excluded, but ancestor records may include changes outside PromptKit. A nonempty
report therefore does not necessarily establish that PromptKit settings changed.
Preserve native ordering, sequence-atomic comparison, and paired redaction;
do not implement a separate subtree comparison algorithm.
- Views compare the same native location even when the application Go root types
differ. Follow upstream's errors for mismatched scopes or unavailable views.
- A valid absent scope still yields a view, allowing history and added/removed
comparisons. Constructor success does not establish effective presence. Rendering
an absent effective value fails without output; explicit null renders normally.
Application-level inspection remains useful for the whole shared configuration.
The focused view adds convenience and supports existing integrations without
claiming exclusive access to PromptKit information. Resource APIs continue to
select and describe logical prompts, profiles, and backends independently of
configuration-tree paths.
### Deferred Independent Source-Version Policies
Different application and component header policies within one load are outside
this initial addition. ConfigKit's existing shared-policy limitation remains.
Planning must document a supported
source/header arrangement using current semantics, including the consequence for source/header arrangement using current semantics, including the consequence for
application and collection documents declaring different specification versions. application and collection documents declaring different specification versions.
Do not imply those headers are independently checked, overwrite the application's Do not imply those headers are independently checked, overwrite the application's
policy, preparse/strip headers, or perform a second load to simulate the deferred policy, preparse/strip headers, or perform a second load to simulate the deferred
capability. Standalone construction retains its applicable native version policy. capability. Standalone construction retains its applicable native version policy.
These deferrals narrow the earlier roadmap and broader upstream request. Neither This remains outside both the accepted upstream addition and this migration;
capability is claimed to be solved by `Value`; both can be revisited separately. neither typed lookup nor focused inspection provides independent version checks.
## Guidance For Implementation Planning ## Guidance For Implementation Planning
### Validate The Pattern Against PromptKit ### Validate The Pattern Against PromptKit
First confirm the final upstream lookup contract and availability. The ConfigKit First confirm the final upstream lookup and inspection contracts and availability.
agent exercised representative one-library and two-library prototypes using The ConfigKit agent exercised representative one-library and two-library prototypes using
existing public callbacks plus a limited top-level lookup shim. Those passed existing public callbacks plus a limited top-level lookup shim. Those passed
checks for defaults, normalization, validation, identities, sensitive inspection, checks for defaults, normalization, validation, identities, sensitive inspection,
trusted secret access, and mounted resource lookup. They were not a production trusted secret access, and mounted resource lookup. They were not a production
@@ -260,6 +306,24 @@ the standalone convenience path through the same rules. Focus on these checks:
engine construction. Verify effective origins and filesystem contexts survive engine construction. Verify effective origins and filesystem contexts survive
mounting, inheritance, and overrides. Document mutation-before-handoff behavior; mounting, inheritance, and overrides. Document mutation-before-handoff behavior;
no mutation-detection subsystem or ConfigKit deep-copy guarantee is required. no mutation-detection subsystem or ConfigKit deep-copy guarantee is required.
4. **Inspection facade and diagnostics.** Retain the native focused view and specify
any public signature changes needed to forward it. `Value` can succeed without
completed-load evidence; do not treat that as proof of a valid inspection view.
The proposed upstream method list does not explicitly include `Diagnostics`.
Resolve forwarding from the original result through PromptKit's consumer-owned
interface, or use an upstream view method if supplied. Preserve useful load
evidence without inventing component-specific diagnostic classification.
5. **CommandKit integration.** Coordinate migration of `ckprompt.ConfigScope` and
resource adapters. Its shared loader currently calls `InspectConfiguration()`
for sources and diagnostics even for resource commands; preserve those commands
and their diagnostics during migration. `ckconfig.View` currently accepts a
concrete `*configkit.Metadata`; forwarding that alone would expose unfiltered
path discovery. Use the view's focused enumeration or apply the selected scope
in the adapter. A PromptKit overview explanation must request `/promptkit`:
the native empty path still selects the whole application. Keep explicit query
paths native and document the broader contextual evidence and ancestor-diff
semantics. Preserve operator capabilities rather than promise unchanged method
signatures or rebuild ConfigKit behavior in CommandKit.
Specify the concrete registration, settings, and constructor shapes, source-helper Specify the concrete registration, settings, and constructor shapes, source-helper
adaptations, and migration examples after these checks. Identify any remaining adaptations, and migration examples after these checks. Identify any remaining
@@ -290,11 +354,21 @@ compatibility resolver.
inside `promptkit`. inside `promptkit`.
- Engine independence from later caller mutation of settings, including nested - Engine independence from later caller mutation of settings, including nested
maps and slices; trusted lookup does not replace redacted inspection. maps and slices; trusted lookup does not replace redacted inspection.
- Resource listings, resource reports, and load diagnostics through the migrated
CommandKit adapters; configuration output and overview explanations focused on
`/promptkit`, with native paths and redaction preserved.
- Focused discovery through the adapter despite unfiltered metadata; explicit
queries outside the focus and shared source/history context retain native behavior.
- Inspection remains frozen after settings mutation; absent, null, historical-only,
and added/removed sections follow upstream semantics. Sibling difference records
are excluded while ancestor differences remain; comparison works across different
application root types selecting the same scope.
The narrower product direction is accepted. Actual PromptKit integration, concrete The product direction, including focused inspection, is accepted. Actual PromptKit
public API shapes, treatment of configuration-inspection availability, and the integration, concrete public API shapes, diagnostic forwarding, CommandKit adapter
supported shared header policy remain planning work. Do not expand these into the migration, and the supported shared header policy remain planning work. Strict
deferred scoped-inspection or independent-version features without a new decision. subtree isolation, a new comparison engine, and independent source-version policies
are not required by this design.
## Further Candidates ## Further Candidates