diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index e53bed1..63f7e29 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -209,10 +209,42 @@ An absent `promptkit` section contributes no application-supplied PromptKit settings; selected bundled underlays can still contribute defaults during the original load. Old root-level keys such as `prompts` and `profiles` are neither consumed nor specially rejected by PromptKit: they may be application settings. -Unknown fields inside `promptkit` remain configuration errors. The application's -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. +Application-specific fields are accepted at the extension points below. The +application's 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. + +### Application-Specific Fields + +**Accepted:** allow additional application-specific fields on prompt, profile, +and backend definitions, on collection definitions, and at the `promptkit` section +level. Use ConfigKit's native string-keyed inline maps (`yaml:",inline"`) in the +public settings model to retain unmatched fields. Recognized fields keep their +typed decoding and semantic validation, including required-field checks. + +Additional fields participate in ordinary ConfigKit composition and remain +available in the resolved application configuration and native configuration +inspection. Applications own their interpretation, validation, and sensitivity +rules. PromptKit ignores these fields during execution; they do not become model +parameters. `extra_params` retains its existing provider-parameter purpose. + +Recommend application-specific grouping, such as an `audita` mapping, to reduce +future field-name collisions; do not require a naming prefix or wrapper. At these +extension points, a misspelled optional PromptKit field can be accepted as an +application field. Accept that tradeoff rather than introduce an extension registry +or custom unknown-field detection. + +These extension points do not change the schemas of nested PromptKit-owned objects +such as output contracts. Maps beneath application-specific keys retain ConfigKit's +ordinary dynamic-value behavior. Standalone and application-owned loading use the +same settings model. + +**Open decision:** whether `InspectPrompt`, `InspectProfile`, and `InspectBackend` +also expose the resource's additional fields, and how those fields appear in their +public reports. Configuration inspection already includes them. Settle resource +reporting separately; acceptance of application fields does not by itself require +adding them to execution objects. ### Focused Configuration Inspection @@ -296,6 +328,8 @@ the standalone convenience path through the same rules. Focus on these checks: registrations when adding PromptKit's rules. Demonstrate explicit callback ordering with a second representative component, without a registry. Keep bundled underlay selection in the original load and specify its consumer API. + Include inline application-field maps at the accepted extension points and + preserve those values during PromptKit normalization. 2. **Per-load presence capture.** The current resolver captures input presence and repair-budget presence in private maps used later during resource construction. Determine which facts can come directly from final metadata and which need @@ -349,8 +383,13 @@ compatibility resolver. - Unavailable paths, found nil values, zero/defaulted settings, and wrong section types; source presence remains distinct from lookup availability. - Missing application settings with bundled defaults enabled and disabled, - application-owned root keys resembling legacy settings, and unknown fields - inside `promptkit`. + application-owned root keys resembling legacy settings, and additional fields + at each accepted extension point. Recognized fields retain type and semantic + validation; nested PromptKit-owned objects retain their existing schemas. +- Additional fields survive native composition, inheritance, normalization, and + configuration inspection, including application-defined sensitivity. They remain + available to application validation and do not enter provider requests merely + because they appear on a resource definition. - 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 PromptKit's @@ -363,8 +402,9 @@ compatibility resolver. are excluded while ancestor differences remain; comparison works across different application root types selecting the same scope. -The product direction, including focused inspection and removal of resource-version -validation, is settled. No product decisions remain before implementation planning. +The product direction includes focused inspection, removal of resource-version +validation, and application-specific fields. Exposure of those additional fields +through resource inspection remains open as described above. Concrete public API shapes, diagnostic forwarding, and verification of the actual PromptKit integration are implementation-planning work.