Record PromptKit feature request decisions

docs/roadmap/promptkit-feature-request.md

@@ -1,15 +1,23 @@
 # PromptKit Feature Request: Mounted Collections And Specification Headers
 
-Status: input destinations are implemented on the ConfigKit development branch
+Status:
-(reviewed at `315f464`). Independent collection specification headers and relative
+
-import destinations are requested additions; not yet accepted or implemented.
+- Input destinations are implemented on the ConfigKit development branch
+  (placement baseline reviewed at `315f464`).
+- Relative import destinations have been accepted and implementation is in
+  progress; the [roadmap](relative-import-destinations.md) owns delivery scope.
+- Source specification headers have been partially accepted in the shared
+  application-version-policy form described below. This does not accept
+  PromptKit's original independent collection-header semantics. Design and
+  implementation of this addition remain separate from relative import work.
 
 ## Requested Capability
 
-Extend the public loading API so independently maintained collections can declare
+Extend configuration loading with relative import destinations and opt-in
-and check their specification compatibility and describe relative import
+checks that contributing sources declare a version accepted by the consumer's
-destinations. Preserve the implemented capability to select a destination mapping
+single configuration specification policy. Preserve the implemented capability
-path for each configuration input. The input's application content contributes
+to select a destination mapping path for each configuration input. The input's
+application content contributes
 beneath that path while retaining ConfigKit's normal composition, precedence,
 inheritance, validation, diagnostics, and inspection behavior.
 
@@ -17,7 +25,9 @@ PromptKit needs this capability for its proposal 3, **Collections With Mounted
 Configuration Fragments**, recorded in PromptKit's
 `docs/roadmap/configuration-collections-mounted-fragments.md`. This request
 describes the public API needs and observable acceptance criteria. It does not
-prescribe ConfigKit's internal design or an implementation plan.
+prescribe ConfigKit's internal design or an implementation plan. The disposition
+and revised source-version scope below supersede conflicting parts of PromptKit's
+original proposal.
 
 The original request targeted ConfigKit v0.7.1. The development branch now
 supplies `Input.Destination` and `SourceInfo.Destination`, as documented in the
@@ -211,8 +221,11 @@ version: "2.4.0"
 Mounted at `[collections, weatherreporter]`, that field is an ordinary collection
 release label. It must not be rejected as an attempt to contribute the protected
 root specification field. The same applies to a prompt's nested optional
-version. Only the main-owned specification declaration uses the application's
+version. This describes the existing placement baseline, with no new source
-configured [VersionRule](../config.md#application-schema-versions).
+checks enabled. The partially accepted extension will reuse the application's
+[VersionRule](../config.md#application-schema-versions) for source declarations;
+header lookup and its interaction with ordinary version payload remain design
+questions, not a guarantee that every source-local `version` stays unchecked.
 
 Conversely, placement must not permit an underlay or imported fragment to claim
 or replace the actual protected specification path or an ancestor that would
@@ -221,9 +234,11 @@ application paths, rather than reserving the spelling `version` in every source.
 Protection must remain valid with imports, inheritance, overlays, and explicit
 CLI overrides.
 
-Retain the main-owned specification check with its existing lifecycle. The new
+Retain existing behavior when the new source checks are not enabled. The
-collection-header checks below are explicit, separate source compatibility
+accepted direction extends the same application version policy across source
-checks; they do not authorize contributions to the main-owned version path.
+files, rather than assigning separate policies to collections. Its interaction
+with protected-path ownership and declaration retention must be designed
+explicitly; it does not implicitly authorize version-field contributions.
 PromptKit does not need main mounted away from the root or integer-to-string
 conversion for every nested ordinary `version` field.
 
@@ -266,87 +281,84 @@ and resource-access behavior. Destinations must participate in documented load
 limits without creating a way to bypass them; this request does not prescribe
 new limit values or their accounting machinery.
 
-## Requested Addition: Independent Collection Specification Headers
+## Partially Accepted Addition: Shared Source Specification Checks
 
-### Consumer Need And Public API
+### Accepted Scope
 
-Allow an application to attach an opt-in source specification rule to a selected
+A ConfigKit consumer defines one configuration specification, which may evolve
-collection entry `Input`. PromptKit would configure the source-local header path
+through versions. `Definition.Version` identifies the declaration path and the
-as `version` and supply its supported-specification policy. ConfigKit owns
+consumer's checker determines which versions are acceptable. The accepted
-checking the declaration and delivering structured diagnostics within the same
+extension lets the consumer apply that same policy across the source files
-`LoadLayered` operation. This must not require PromptKit to open, parse, or load
+contributing to a configuration, rather than checking only the main declaration.
-collection manifests separately.
+It does not introduce independent collection or subtree specification policies.
 
-Reuse the public version vocabulary where appropriate: the checker should be
+The consumer can opt in with increasing strictness:
-able to distinguish absent, null, string, and strict decimal-integer declarations
-and receive their text without imposing SemVer. For PromptKit specification 1,
-`version: 1` and `version: "1"` can express the same supported identifier.
-PromptKit decides which declarations it accepts, including whether a missing
-header is an error. Exact API names and how the source rule relates to the
-existing `VersionRule` type are ConfigKit design decisions.
 
-This is a separate rule from `Definition.Version`, which continues to describe
+1. **Current behavior:** retain existing loading and version-checking behavior,
-the main-owned application specification. It checks a source's declared format,
+   including existing protected-path restrictions. No new source-header check.
-not its complete domain schema. Domain validation still runs on final effective
+2. **Check declarations when present:** a source that declares a version must
-configuration, not once per collection or fragment.
+   satisfy `Definition.Version`; omission is allowed.
+3. **Require declarations:** every participating source must declare a version
+   that satisfies `Definition.Version`; omission is an error.
 
-The minimum API must support several collection entry inputs in one load, each
+Acceptance is determined by the existing consumer-supplied checker, not by a
-with a destination and an explicitly assigned source-header policy. Source
+new ConfigKit-owned expected string or automatic equality with the main file's
-selection determines which documents are entries. Neither a filename nor the
+declaration. A consumer may accept several compatible versions. A declaration
-mere presence of a field named `version` automatically enables header checking.
+rejected under the selected mode fails the attempted load through structured
-No YAML-selected executable checker or general source-validation callback is
+errors, with no usable partial result; a higher-precedence payload cannot turn
-requested.
+an incompatible source declaration into an acceptable one.
 
-### Header Scope And Payload
+This establishes that checked sources declare an accepted specification version.
+It does not prove that every fragment conforms to its declaration. Existing
+final decoding and application validation still determine the validity of the
+assembled configuration; fragments are not independently loaded as complete
+applications.
 
-Recommend one required specification declaration per selected collection entry,
+### Difference From PromptKit's Original Proposal
-with its ordinary imported fragments authored under that declared specification.
-Do not require a repeated header in every prompt/profile fragment. Importing a
-fragment does not give it an independent header rule; in particular, its ordinary
-release or prompt `version` must not be consumed as a specification header.
 
-For an explicitly configured entry, check its own declaration independently of
+PromptKit originally requested explicitly selected collection-entry rules,
-other inputs and precedence layers. Another source cannot supply a missing
+separate from `Definition.Version`, with ordinary imports exempt from independent
-header, and a higher-priority override cannot conceal an unsupported declaration.
+checks. It also recommended consuming accepted entry headers and exposing them
-Any rejected entry fails the whole load with no usable partial result, even if
+as source evidence while leaving imported release metadata untouched.
-its payload would subsequently be superseded. Reusing a physical source across
-allowed separate tiers retains existing source-reuse semantics; this request
-adds no source-uniqueness policy.
 
-After an entry header is accepted, recommend consuming it as structural source
+That full set of semantics has not been accepted. The accepted direction uses
-metadata: it does not contribute at the mounted application path. For example,
+one shared `Definition.Version` policy and optional or required declarations
-entry `version: 1` must not become `collections.weatherreporter.version`. The
+across participating sources. Separately versioned subsets or collections are
-collection release label can be contributed separately as ordinary payload.
+outside this addition's scope and may be considered independently in the future.
-This distinction also prevents unrelated collection specification declarations
+Header consumption and inspection from the original proposal remain design
-from conflicting during strict composition.
+suggestions, not accepted requirements.
 
-This consumption applies only to the explicitly selected source header. It
+### Remaining Design Work
-must not remove nested versions, imported metadata, or the main application's
-existing version field. The API should make the distinction between a consumed
-source header and a retained main declaration explicit; it must not silently
-change existing `Definition.Version` behavior.
 
-### Diagnostics And Inspection
+The following details remain to be resolved before implementation:
 
-Expose the checked declaration and its source-local location through supported
+- How the configured declaration path is interpreted for individual sources,
-source inspection, or equivalent public metadata. Consumers should be able to
+  particularly before destination placement.
-identify the source, header path, and accepted declaration without rereading
+- Which source kinds and roles participate, including direct underlay inputs,
-files. Preserve the normal distinction between authored input evidence and
+  transitive imports, and other contributions.
-rendered effective application configuration: a consumed header is evidence of
+- Whether checked declarations are consumed or retained, how that interacts
-source compatibility, not an effective domain field.
+  with composition and main-owned version protection, and what inspection
+  evidence is exposed.
+- How null and malformed declarations behave in each mode, preserving the
+  distinction between absence and a present declaration and considering the
+  existing string/decimal-integer version vocabulary.
+- The opt-in API, callback lifecycle, and source-local diagnostic attribution.
 
-Header failures and warnings should use ConfigKit's structured diagnostics and
+In particular, the original example of an imported `version: "2.4.0"` release
-normal disclosure rules. Report the actual entry source and header location,
+label is not guaranteed to remain outside checking in an enabled mode. That
-or a source-location fallback when the header is absent; do not attribute them to the
+depends on the chosen header lookup semantics. No automatic field consumption,
-unrelated protected root field or invent an effective payload field. The
+new coercion, or per-collection checker should be inferred from partial acceptance.
-source's destination remains inspectable. Exact diagnostic codes and inspection
-types are left to ConfigKit.
 
 ## Requested Addition: Relative Import Destinations
 
+Disposition: accepted; implementation is in progress under the
+[relative import destinations roadmap](relative-import-destinations.md).
+The behavior below records the accepted capability; exact syntax and completion
+status follow that work, rather than implying a released feature.
+
 Extend the public YAML import directive so a `path` or `glob` import can specify
-a relative destination as literal mapping-key segments. An illustrative spelling
+a relative destination as literal mapping-key segments. The roadmap selects
-is `destination: [prompts]`; the exact directive field name remains a proposal.
+`destination` as a sequence of strings, for example `destination: [prompts]`.
 
 The public behavior should be:
 
@@ -375,13 +387,13 @@ This is declarative access to the existing placement capability. It does not
 request recursive glob syntax, implicit directory scanning, namespace inference,
 or a new composition strategy.
 
-## Combined Collection Entry Example
+## Relative Import Collection Entry Example
 
-With both additions, an entry document selected by the application with a source
+An entry document selected by the application with destination
-header rule and destination `[collections, weatherreporter]` could contain:
+`[collections, weatherreporter]` could describe its layout as follows. This
+example illustrates relative imports only and assumes no new source checks:
 
 ```yaml
-version: 1
 configkit:
   imports:
     - path: metadata.yml
@@ -398,18 +410,16 @@ glob assumes matching files; collections can omit unused categories or use
 existing optional-import behavior. The application still selects and provisions
 the collection and assigns its namespace. ConfigKit does not discover it.
 
-The entry's `version: 1` is checked and consumed. Its `metadata.yml` can contain
+With current source-version behavior, `metadata.yml` can contain
-`version: "2.4.0"`, retained as the collection's ordinary release label because
+`version: "2.4.0"` as an ordinary mounted collection release label. Prompt
-that import has no independent header rule and inherits the collection
+fragments retain local mapping keys and optional prompt versions, and contribute
-destination. Prompt fragments retain local mapping keys and optional prompt
+beneath the collection's `prompts` mapping. The main application can retain its
-versions, and are placed beneath the collection's `prompts` mapping. The main
+own version declaration. Enabling the proposed shared source checks may require
-application can independently retain its own `version: 1` declaration.
+changes to these files once declaration lookup and retention are defined.
 
-Thus publishers can describe their collection layout, authors can keep compact
+Publishers can describe collection layout while applications select collections
-fragments, and operators can compose several independently checked collections
+and destinations. The later shared-version feature will add opt-in declaration
-without application-side source rewriting. These checks establish declared
+checking; it does not establish package authenticity or release integrity.
-specification compatibility, not package authenticity, release integrity, or
-proof that every fragment was authored correctly.
 
 ## Deferred And Excluded Work
 
@@ -432,7 +442,10 @@ inventory, and execution APIs remain PromptKit responsibilities.
 
 ## Public Acceptance Scenarios
 
-Evaluate the extension through supported public loading and inspection APIs:
+Evaluate the implemented placement baseline and accepted relative-import
+extension through supported public loading and inspection APIs. Source-version
+rows below express the partially accepted direction; their unresolved details
+must be settled before they become implementation acceptance tests.
 
 | Scenario | Expected consumer-visible result |
 | --- | --- |
@@ -444,27 +457,33 @@ Evaluate the extension through supported public loading and inspection APIs:
 | Version-only prompt override | Label changes; omitted prompt body fields survive |
 | Nested mounted import without a destination directive | Imported fields contribute at the inherited destination |
 | Local profile inheritance across mounted peer fragments | Parent resolves at the effective sibling scope |
-| Collection metadata containing `version` mounted below root | Ordinary nested field, independent of root VersionRule |
+| Collection metadata containing `version` mounted below root, with new checks disabled | Existing ordinary nested-field behavior |
 | Mounted/imported contribution actually targeting the protected version path | Rejected under version ownership rules |
 | Mounted field using source-relative content, including inheritance | Original declaring resource context remains available |
 | Mounted explicit null and omitted field | Distinct effective presence information |
 | Mounted validation error or secret field | Effective paths, physical locations, and existing disclosure rules agree |
 | File, native filesystem, byte, reader, or mapping input with equivalent content | Equivalent application values, subject to existing source contracts |
 | Unsupported destination or failed load | Normal structured failure, no usable partial result |
-| Several collection entries with supported specification headers | Each declaration is independently accepted; payloads compose normally |
+| Source-version checks disabled | Existing version-checking and protected-path behavior |
-| Missing, null, malformed, or unsupported entry header | ConfigKit reports structural/type errors or invokes the configured version policy as appropriate; rejection fails the whole load |
+| Check-when-present mode, declaration absent | Omission is allowed |
-| Unsupported entry superseded by a higher layer | Compatibility failure remains visible and fails loading |
+| Check-when-present mode, declaration present | Must satisfy the shared `Definition.Version` policy |
-| Consumed entry header plus imported release metadata | Header is inspectable as source evidence; only the release label becomes the collection's ordinary version field |
+| Required mode, declaration absent | Structured load failure |
-| Ordinary imported fragment containing `version` without a header rule | Field remains ordinary payload and is not independently consumed or checked |
+| Required mode, declaration present | Must satisfy the shared `Definition.Version` policy |
+| Different declarations both accepted by the consumer checker | No additional exact-equality requirement |
+| Rejected source declaration with payload superseded by a higher layer | Rejection still fails the load |
 | Relative import destination omitted or empty | Existing inherited-destination behavior |
 | Entry at `[collections, weather]`, import at `[prompts]`, nested import at `[extras]` | Nested contribution appears beneath `[collections, weather, prompts, extras]` |
 | Glob import with a relative destination | Every matched contribution uses that destination and composes strictly |
 | Relative import destination with source-relative resource | Effective configuration path changes; resource base remains the declaring source |
-| Load without source-header rules or relative import directives | Existing loading and main VersionRule semantics remain unchanged |
+| Load without new source checks or relative import directives | Existing loading and main VersionRule semantics remain unchanged |
 
-The requested outcome is a consumer that selects collection entry sources,
+The relative-import outcome is a consumer that selects entry sources and
-destinations, and specification policies, performs one ordinary layered load,
+destinations, performs one ordinary layered load, and receives final typed
-and receives final typed configuration with reliable diagnostics and inspection.
+configuration with reliable diagnostics and inspection. Entry documents describe
-Collection entries describe their own relative import placements, and unsupported
+their own relative import placements without consumer-side source rewriting,
-source specifications fail independently of payload precedence. It should need no
+generic merging, or provenance reconstruction.
-consumer-side source rewriting, generic merging, or provenance reconstruction.
+
+The separately scoped, partially accepted source-version extension adds optional
+or required declaration checking through the consumer's single
+`Definition.Version` policy. It does not require or authorize independently
+versioned collections.