Adopt focused ConfigKit inspection in configuration roadmap
This commit is contained in:
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user