diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 6b0f97a..e53bed1 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -201,9 +201,9 @@ appropriate nested location. Source-relative context follows the effective contributing field, not the location of the application document or mount point. ConfigKit-owned headers and directives retain their native semantics. The -application owns its main configuration specification; PromptKit's registration -must not replace that policy with its standalone document version rule. -Independent source-version policies are deferred as described below. +application owns its configuration version policy. PromptKit's registration +preserves that policy; PromptKit-specific resource version validation is removed +as described below. An absent `promptkit` section contributes no application-supplied PromptKit settings; selected bundled underlays can still contribute defaults during the @@ -226,8 +226,7 @@ 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. +path. This replaces the earlier inspection deferral. The view is a reporting focus, not an isolation or access-control boundary. Accept ConfigKit's native behavior: @@ -261,28 +260,29 @@ 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 +### Resource Version Validation -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. +**Accepted:** this migration gives up PromptKit-specific validation of `version` +fields in resource documents, including collection, prompt, and profile +definitions. This is an intentional simplification with a small practical cost, +not an unresolved compatibility requirement or a prerequisite for an upstream +version-policy feature. -This remains outside both the accepted upstream addition and this migration; -neither typed lookup nor focused inspection provides independent version checks. +The application retains ownership of ConfigKit's version policy. ConfigKit-owned +headers and directives follow that policy and native composition semantics; +PromptKit adds no separate resource-version checks. Apply this resource decision +to both application-owned loading and standalone construction. Update examples +and migration guidance accordingly, without preparsing or stripping headers or +adding a second load. ## Guidance For Implementation Planning ### Validate The Pattern Against PromptKit 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, +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 `Value` implementation or a real PromptKit integration. @@ -307,23 +307,22 @@ the standalone convenience path through the same rules. Focus on these checks: 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. + public signatures for its operations and load-diagnostic forwarding. Obtain + diagnostics from the original result through PromptKit's consumer-owned + interface, or use an upstream view method if supplied. Expose focused enumeration + alongside native metadata and query operations. A PromptKit overview explanation + selects `/promptkit`; the native empty path selects the whole application. + +Document what the interfaces do: their inputs, operations, outputs, and errors, +and how registration, loading, and engine construction fit together. Keep this +guidance concrete; hypothetical misuse does not call for registration tracking, +another validation lifecycle, or defensive caveats. + +CommandKit neutrally exposes upstream PromptKit APIs. Any adapter updates are +routine downstream adoption, not a constraint on PromptKit's public API or a +prerequisite for completing this migration. PromptKit's implementation plan covers +its own resource, inspection, and diagnostic capabilities; CommandKit owns how +those are presented through CLI commands. Specify the concrete registration, settings, and constructor shapes, source-helper adaptations, and migration examples after these checks. Identify any remaining @@ -354,21 +353,20 @@ 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 +- Resource listings, resource reports, and load diagnostics through PromptKit's + public APIs; configuration output and overview explanations focused on `/promptkit`, with native paths and redaction preserved. -- Focused discovery through the adapter despite unfiltered metadata; explicit +- Focused enumeration alongside 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 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. +The product direction, including focused inspection and removal of resource-version +validation, is settled. No product decisions remain before implementation planning. +Concrete public API shapes, diagnostic forwarding, and verification of the actual +PromptKit integration are implementation-planning work. ## Further Candidates