# PromptKit Request: Consume A Component From One Resolved Application Configuration Status: upstream feature request for discussion, not an accepted implementation plan. This document specifies consumer capabilities and leaves API names and internal implementation to ConfigKit. ## Consumer Need PromptKit is a Go library used by applications such as Audita and Scriptorium. Today, an application can load its own settings with ConfigKit, then assemble separate sources for PromptKit to load again. Audita uses the application main source's recorded filesystem context to locate companion PromptKit resources. The desired workflow is one application-owned ConfigKit load. The application passes the **entire resolved result** to PromptKit, which consumes only the fixed root-level `promptkit` section. The application should not extract, serialize, reshape, or reload that section, or reconstruct its resource contexts. The resulting document can contain both sets of settings: ```yaml version: 3 application: output_directory: ./reports promptkit: schema_root: ./schemas collections: weatherreporter: prompts: - id: summarize.alerts messages: - role: user content_file: ./messages/summary.md output: format: json validation_mode: json_schema schema_path: alerts.json ``` This is an illustrative target configuration, not current PromptKit syntax. The fixed key is PromptKit's convention, not a proposed ConfigKit reserved key. Applications retain source discovery, layering, imports, and override policy. PromptKit retains its field rules and engine construction. ConfigKit retains composition, effective field contexts, and inspection semantics. ## Verified Baseline Assessment baseline: ConfigKit v1.3.0, commit `652ddb649c60208dbba964f0ef919e36725c12c0`. Public-API offline diagnostics verified: - A typed component field and an inline catch-all map can allow application siblings while rejecting unknown fields inside the component. - Application callbacks can default component values after composition; registered identities can validate nested resource lists. - Mounted fragments retain field origins and usable `SourceContext` information. - `Explain` on the component path returns a redacted section snapshot. - `WriteEffective` and `Diff` still operate on the whole result. A sibling-only change produces a native difference outside the component. - One shared source-version rule accepting application version 3 rejects a PromptKit fragment declaring version 2. The relevant public contracts are [definitions and results](../../lifecycle.go), [resource contexts](../../resource_context.go), [inspection](../../inspection.go), [metadata](../../metadata.go), [comparison](../../diff.go), and [shared source-version checks](../config.md#shared-source-version-checks). These findings establish partial feasibility, not a working whole-result PromptKit integration. ## 1. Resolved Component Access And Scoped Inspection Provide a public way for a library receiving the whole application result to select its section for execution and inspection, independently of the application's particular Go root type. It must retain the original load's effective values and resource contexts without another configuration load or historical reconstruction. Execution access must provide usable, trusted configuration values. Existing redacted inspection YAML is not an execution input. Define ownership explicitly: `Result.Config` is mutable while inspection describes a frozen snapshot today. The new contract should state which values a consumer receives and how later caller mutations relate to those values and their inspection evidence. This request does not require all existing `Result.Config` values to become immutable. For the selected section, support: - Effective configuration output, with native redaction. - Presence/origin queries, relevant history, and path enumeration. - Explanations retaining full native paths such as `/promptkit/collections/weatherreporter/prompts/0/output`. - Comparison of the section between successful loads, retaining native sensitive change semantics and excluding changes confined to sibling application values. - Effective field context lookup so relative message and schema files keep the filesystem and base directory of the source that contributed the field. Define absent-section and explicit-null behavior, including comparisons where a section is added or removed. A component view must not turn an absent section into a new composition operation. Scope value-bearing reports and history so selecting a component does not disclose unrelated sibling values through ancestor records. Relevant source provenance remains useful; no requirement is made to hide the existence of a shared source document. This is a request for a native consumer boundary, not a guarantee about which nodes ConfigKit may visit internally. Whole-result comparison followed by local filtering can approximate the public diff, but leaves PromptKit maintaining separate adapters for output, opaque metadata, history, and comparison. ## 2. Independent Source-Version Policies Within One Load An application's main configuration and imported component collections can have independent specification versions. For example, the application document above uses `version: 3`, while a PromptKit collection can begin with: ```yaml version: 2 prompts: - id: summarize.alerts messages: - role: user content: Summarize the supplied alerts. output: format: text validation_mode: none ``` The application mounts that standalone collection beneath `promptkit.collections.weatherreporter`. Its version declaration should be checked against PromptKit's collection policy, not the application's version policy. Provide public selection of the appropriate version policy for component sources and their imports within the same load. Define the selection behavior for direct inputs, transitive imports, and sources mounted at destinations. Policy assignment must be explicit and independent of whether a declaration's numeric value happens to match one checker; accepting both 2 and 3 everywhere does not meet this need. Preserve optional declarations: a collection may omit its header, but a supplied header must be checked under the applicable policy before composition consumes it. Maintain ordinary final-value validation and native diagnostics. Header handling must not let a collection overwrite the application's main version declaration. The application must not preparse fragments, strip headers, or load collections separately to achieve this behavior. No particular selector syntax or internal routing mechanism is requested. An application-owned document containing `promptkit` settings is still an application document; it does not require two competing root version headers. ## 3. Demonstrate A Small Component Integration Contract Please evaluate this complete consumer sequence alongside the requested APIs: 1. The application declares its own configuration type and includes PromptKit's supported public settings/registration at `promptkit`. 2. It incorporates PromptKit-owned defaults, normalization, validation, sequence identities, and sensitivity rules into its ordinary ConfigKit load. Desired bundled resources enter as ordinary underlays before resolution. 3. ConfigKit loads and resolves the complete configuration once, applying the application's rules and the component's rules in the supported lifecycle. 4. The application passes that whole result to PromptKit. PromptKit uses the fixed section and original source contexts to capture resources and construct its engine. It does not inject defaults through a second load. 5. PromptKit delegates its configuration reports and comparisons to the native scoped inspection capability. Existing `Definition[T]` callbacks may be sufficient with a small library helper. A new component registry is **not** a prerequisite of this request. Please show how component rules can be composed with an application-owned root type without the application reproducing those rules or depending on the library's internal types. If a public extension is needed, keep it limited to the demonstrated gap. The section handoff should not require a per-application extraction adapter. ## Acceptance Scenarios - One load contains application fields and a typed PromptKit section; unrelated fields are governed by the application, while invalid component fields fail. - Component defaulting, normalization, identities, and sensitivity run through the normal lifecycle and remain visible in the resolved result and inspection. - Whole-result handoff works with an application-owned Go configuration type, with no section serialization/reload or source-context reconstruction. - Embedded and operator collection fragments retain relative-file contexts after mounting, inheritance, and overrides, including identical file basenames. - Component execution access preserves values needed for execution, while public inspection redacts sensitive values. Ownership/mutation behavior is documented. - Sibling-only changes do not appear in component comparisons; component changes, sensitive changes, and section addition/removal follow native reporting rules. - Application version 3 and PromptKit collection version 2 coexist under their respective policies; each rejects unsupported declarations independently. Headerless collections and transitive imports exercise the selected policies. PromptKit's repair-default change and its domain-specific validation rules are outside this upstream request. No changes to ConfigKit's internal representation, algorithms, or package layout are proposed. Please distinguish capabilities already available through a concise public example from those needing new public APIs.