Retire unselected collection configuration proposals
This commit is contained in:
@@ -1,15 +1,15 @@
|
||||
# Proposal 3: Collections With Mounted Configuration Fragments
|
||||
|
||||
Status: proposed PromptKit standard; not implemented in PromptKit. Required
|
||||
Status: selected configuration direction; not implemented in PromptKit. Required
|
||||
ConfigKit capabilities are implemented on its development branch, reviewed at
|
||||
`e66c371` on 2026-10-16, but are not in PromptKit's selected v0.7.1 dependency.
|
||||
The recommended direction uses collection-local mapping keys, one installed
|
||||
definition per prompt, and an optional flat prompt `version` field. The latest
|
||||
review agrees on shared source checks using `IfPresent` and a distinct collection
|
||||
`release_version` field; remaining PromptKit decisions are listed below. Compare
|
||||
[proposal 1](configuration-collections-current-configkit.md) and
|
||||
[proposal 2](configuration-collections-identified-records.md); the parent
|
||||
[namespace roadmap](namespaces.md) owns the shared decisions.
|
||||
`release_version` field; remaining PromptKit decisions are listed below. The
|
||||
parent [namespace roadmap](namespaces.md) owns the shared decisions. Unselected
|
||||
proposals 1 and 2 have been retired; their history and the separately captured
|
||||
upstream request are recorded below.
|
||||
|
||||
## Recommendation
|
||||
|
||||
@@ -25,8 +25,8 @@ keys after ConfigKit hands off the resolved configuration.
|
||||
|
||||
There is one installed definition per qualified prompt ID. Its optional
|
||||
`version` field describes that definition; it does not create another identity
|
||||
or select a merge strategy. This removes the need for proposal 2's identified
|
||||
record sequences and for the current nested prompt-version mapping.
|
||||
or select a merge strategy. This avoids identified record sequences and the
|
||||
current nested prompt-version mapping.
|
||||
|
||||
Placement belongs to ConfigKit. PromptKit must not parse, wrap, or rewrite each
|
||||
source itself, nor impose duplicate-namespace checks before composition. This
|
||||
@@ -241,8 +241,8 @@ To retain unqualified application resources, recommend optional root-level
|
||||
using the same definition shapes. They produce unqualified public IDs. Under
|
||||
this proposal, namespaced definitions belong under `collections`, not a second
|
||||
qualified-key spelling in those root maps. This avoids two configuration paths
|
||||
producing the same public identity. This representation is a recommendation
|
||||
for proposal 3, not a change to today's accepted format.
|
||||
producing the same public identity. This representation belongs to the selected
|
||||
future direction; it does not change today's implemented format.
|
||||
|
||||
Stored references such as `default_profile`, profile `backend`, and smoke-test
|
||||
profile defaults remain exact public references. Nesting does not automatically
|
||||
@@ -272,10 +272,9 @@ is a simpler alternative but requires more consumer changes; settle the public
|
||||
API shape before implementation. Listings should identify one prompt per ID
|
||||
and expose the optional declared version separately from identity.
|
||||
|
||||
This intentionally supersedes multi-version preservation for this alternative.
|
||||
Proposals 1 and 2 retain their earlier assumptions for comparison. The parent
|
||||
roadmap's version-selection and listing language needs corresponding revision
|
||||
if proposal 3 is adopted.
|
||||
This deliberately replaces the earlier multi-version preservation assumption.
|
||||
The selected direction identifies prompts by ID and exposes an optional version
|
||||
label; the request-version and listing API details remain open below.
|
||||
|
||||
## ConfigKit Composition Boundary
|
||||
|
||||
@@ -346,8 +345,8 @@ unsupported declarations through the ConfigKit checker. The handling of an
|
||||
absent main declaration remains an explicit decision below. Accept additional
|
||||
versions only when PromptKit actually supports their format semantics: accepting
|
||||
a header does not migrate its payload or independently validate a fragment's
|
||||
complete schema. The three proposals are alternative candidate formats, not
|
||||
interchangeable released meanings of specification version 1.
|
||||
complete schema. The retired proposals were alternatives, not released formats
|
||||
sharing specification version 1.
|
||||
|
||||
The selected initial direction is `SourceVersionModeIfPresent`:
|
||||
|
||||
@@ -424,25 +423,33 @@ historical source ownership, or proof of unchanged published contents. Operator
|
||||
overrides may change resources while retaining a release label. Engine
|
||||
construction captures definitions; edits require a replacement engine.
|
||||
|
||||
## Comparison And Migration
|
||||
## Retired Alternatives And Upstream Request
|
||||
|
||||
| Concern | Proposal 1 | Proposal 2 | Proposal 3 |
|
||||
| --- | --- | --- | --- |
|
||||
| Author identity | Qualified mapping key | Namespace/local-ID fields | Local mapping key beneath a mounted collection |
|
||||
| Prompt version | Required nested key | Required identity field | Optional descriptive field |
|
||||
| Multiple installed versions per prompt | Supported | Supported | Not supported |
|
||||
| Repeated resource wrapper in fragments | Required | Required | Omitted through placement |
|
||||
| Composition machinery | Existing mappings | Identified record sequences | Existing mappings after placement |
|
||||
| Upstream prerequisite | None beyond its original baseline | Proposed record composition and inheritance | Placement, relative imports, and shared source checks implemented in development |
|
||||
| Cross-collection inheritance | Existing qualified sibling keys | Proposed tuple references | Requires a separate extension or authored flattening |
|
||||
| Source specification checks as described | Main only | Main only | Shared policy; non-main declarations checked when present |
|
||||
The unselected proposals were retired after the identified-record design was
|
||||
captured for separate upstream consideration. Both original documents remain
|
||||
available in PromptKit Git history at `b5866dd`:
|
||||
|
||||
Proposals 1 and 2 retain their original assumptions for historical comparison.
|
||||
Proposal 3 is the recommended direction for the stated one-installed-prompt
|
||||
requirement. Its authoring economy follows from the configuration hierarchy,
|
||||
and it retains ordinary map composition. The tradeoffs are explicit assembly
|
||||
destinations, changed inheritance scope, and a deliberate reduction of prompt
|
||||
version selection to one installed definition.
|
||||
```sh
|
||||
git show b5866dd:docs/roadmap/configuration-collections-current-configkit.md
|
||||
git show b5866dd:docs/roadmap/configuration-collections-identified-records.md
|
||||
```
|
||||
|
||||
Proposal 1 used fully qualified mapping keys and the then-current ConfigKit
|
||||
composition behavior. Proposal 2 used explicit identity fields in record
|
||||
sequences and requested identity-based composition and inheritance. Neither is
|
||||
an active PromptKit implementation option. The selected mounted-mapping design
|
||||
meets the one-installed-prompt requirement with compact local keys and ordinary
|
||||
mapping composition.
|
||||
|
||||
Proposal 2's generic extension is preserved in the ConfigKit repository as
|
||||
`docs/roadmap/promptkit-identified-records-feature-request.md`. It requests
|
||||
explicit record-identity registration, composition and overlay by identity,
|
||||
record inheritance, deterministic ordering, and coherent inspection. That
|
||||
request is for upstream evaluation, not an accepted ConfigKit capability or a
|
||||
prerequisite of this roadmap. Retirement does not resolve the six remaining
|
||||
PromptKit decisions below.
|
||||
|
||||
## Migration
|
||||
|
||||
Migration must choose one installed definition for each former multi-version
|
||||
prompt, move any retained version into its optional field, and relocate
|
||||
@@ -524,7 +531,6 @@ remain before the PromptKit contract is complete:
|
||||
and migration examples. Direct mounted fragments remain a useful alternative
|
||||
for applications that already assemble sources themselves.
|
||||
|
||||
The parent roadmap still owns the overall configuration decision. Its older
|
||||
version-selection and metadata examples describe earlier alternatives; adopting
|
||||
this standard requires reconciling those details and updating current contracts
|
||||
when implementation lands.
|
||||
The parent roadmap records this selected direction. Resolve the remaining
|
||||
PromptKit choices here and update current contracts when implementation lands;
|
||||
retiring the alternatives does not authorize feature implementation.
|
||||
|
||||
Reference in New Issue
Block a user