diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index cbc8332..6b0f97a 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -52,8 +52,9 @@ unchanged; the change does not promise successful correction. **Accepted:** the application composes configuration once through ConfigKit and passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit -locates the fixed root-level `promptkit` section and consumes only that section, -ignoring sibling application settings. The application does not extract, reshape, +locates the fixed root-level `promptkit` section and consumes only that section +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 key. @@ -88,7 +89,11 @@ profile selection, required-resource checks, or diagnostics policy. ### 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 func (r *Result[T]) Value(path Path) (any, bool) @@ -145,6 +150,7 @@ type Configuration interface { Value(configkit.Path) (any, bool) Metadata() configkit.Metadata 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 authoritative; do not recover a missing effective location from historical evidence. 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; 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 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, -metadata/history, explanations, and comparison are outside this initial addition. -`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. +**Accepted:** preserve resource listing and inspection, and provide configuration +reporting through ConfigKit's proposed non-generic `Inspection` view: -**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 +```go +inspection, ok := result.InspectSubtree(configkit.Keys("promptkit")) +``` + +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 application and collection documents declaring different specification versions. 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 capability. Standalone construction retains its applicable native version policy. -These deferrals narrow the earlier roadmap and broader upstream request. Neither -capability is claimed to be solved by `Value`; both can be revisited separately. +This remains outside both the accepted upstream addition and this migration; +neither typed lookup nor focused inspection provides independent version checks. ## Guidance For Implementation Planning ### Validate The Pattern Against PromptKit -First confirm the final upstream lookup contract and availability. The ConfigKit -agent exercised representative one-library and two-library prototypes using +First confirm the final upstream lookup and inspection contracts and availability. +The ConfigKit agent exercised representative one-library and two-library prototypes using existing public callbacks plus a limited top-level lookup shim. Those passed checks for defaults, normalization, validation, identities, sensitive inspection, 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 mounting, inheritance, and overrides. Document mutation-before-handoff behavior; 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 adaptations, and migration examples after these checks. Identify any remaining @@ -290,11 +354,21 @@ compatibility resolver. inside `promptkit`. - Engine independence from later caller mutation of settings, including nested 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 -public API shapes, treatment of configuration-inspection availability, and the -supported shared header policy remain planning work. Do not expand these into the -deferred scoped-inspection or independent-version features without a new decision. +The product direction, including focused inspection, is accepted. Actual PromptKit +integration, concrete public API shapes, diagnostic forwarding, CommandKit adapter +migration, and the supported shared header policy remain planning work. Strict +subtree isolation, a new comparison engine, and independent source-version policies +are not required by this design. ## Further Candidates