eric/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle collection configuration decisions around simplicity

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-16 13:50:40 +00:00
parent 190ec69345
commit ddda2f8767
2 changed files with 145 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/roadmap/configuration-collections-mounted-fragments.md
View File

@@ -6,11 +6,26 @@ ConfigKit capabilities are implemented on its development branch, reviewed at
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. The
parent [namespace roadmap](namespaces.md) owns the shared decisions. Unselected
`release_version` field. The six configuration decisions below are accepted;
exact public API shapes remain delivery details. 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.
## Configuration Simplicity
This development round simplifies configuration authoring and consumption:
- Load prompt, profile, and backend libraries as YAML configuration, removing
mandatory catalog Go-module imports and bundled profiles.
- Remove the unused prompt-version selection scheme and its request API fields.
- Let publishers opt into specification checks by declaring a source-root
`version`, commonly in a collection entry. Neither entries nor individual
fragments must declare it; authors need not add headers to every file.
Prefer conventions and small convenience APIs over mandatory workflows.
Preserve consumer choice over sources, layout, namespaces, and precedence without
adding speculative options or stronger compatibility/provenance guarantees.
## Recommendation
Use ConfigKit's implemented input destinations and relative import destinations.
@@ -141,12 +156,13 @@ entry := configkit.Input{
}
```
Put peer collection entries into one `Underlay` group's `Inputs`. Configure
`LayeredOptions.SourceVersionMode` as `SourceVersionModeIfPresent` and
For independent peer collections, one `Underlay` group's `Inputs` is a useful
starting point, not a required grouping. Consumers choose precedence and groups.
Configure `LayeredOptions.SourceVersionMode` as `SourceVersionModeIfPresent` and
`Definition.Version.Path` as `configkit.Keys("version")`, with PromptKit's
supported-specification checker. The application main input remains at the
root and declares `version: 1` in the examples below. Namespace selection and
source selection require no manifest parsing in PromptKit.
root and declares `version: 1` in the examples below; both the main input and
its declaration are optional. Namespace and source selection require no manifest parsing in PromptKit.
| Selected source | Effective destination |
| --- | --- |
@@ -160,8 +176,11 @@ Directly selected fragments with `Input.Destination` remain possible. Entry
imports are the recommended packaging convention because publishers can describe
their layout. Filenames and directory basenames do not define resource identity;
no implicit directory discovery, namespace inference, or collection installer is
introduced. A helper may construct inputs from explicit source selections but
must not inspect manifests to compute their destinations.
introduced. A small helper should construct inputs from an explicitly selected
source and namespace, without inspecting manifests to compute destinations. `collection.yml`
is a convention, not a required filename. Direct fragments and programmatic
sources remain supported through the source API; no parallel collection loader
or mandatory filesystem layout is introduced.
Use later underlay groups or main for intentional application/operator overrides.
Placement does not establish precedence. Do not also recursively scan files
@@ -256,25 +275,17 @@ The resource's qualified ID is its sole configuration identity. There is no
version-key mapping, implicit `latest`, version ordering, or parallel installed
history. Updating the optional version changes metadata on the same prompt.
Recommend a nonblank opaque string when a prompt version is supplied, with no
SemVer constraint. Omission or explicit null means no declared version; null
can clear a lower-layer or inherited label. Quote numeric-looking labels such
as `"1"`. Do not synthesize a version for an unversioned prompt. These detailed
value rules are recommendations; the agreed requirement is that the field be
optional.
An optional prompt version is an opaque string with no SemVer, nonblank, or
normalization requirement. Omission or explicit null means no declared label;
null can clear a lower-layer or inherited label. Quote numeric-looking labels
such as `"1"`. Preserve supplied strings, including empty strings, and distinguish
an absent label in inspection. Do not synthesize a version.
Execution and inspection without a requested version select the installed
prompt directly. As an API migration recommendation, retain an optional
requested version as an exact assertion against the installed label: a match
succeeds; a mismatch or an unversioned definition fails the assertion. It never
searches for another version. Removing request-side version fields altogether
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 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.
Remove request-side prompt-version fields, version selection, ordering, and
version defaults as part of the breaking change. Do not reinterpret those fields
as exact-match assertions. Execution and inspection resolve the installed prompt
by ID alone. Listings expose one prompt per ID with its optional descriptive
label separately. A label neither controls execution nor proves unchanged content.
## ConfigKit Composition Boundary
@@ -322,17 +333,14 @@ now ordinary optional fields, would inherit and overlay like other fields;
Cross-collection profiles are no longer immediate siblings. Consequently,
`extends: provider/brief` cannot reach that collection under current ConfigKit
inheritance. Recommend local sibling inheritance for the initial proposal;
applications can still execute or select the qualified `provider/brief`
profile directly. Migrating existing cross-collection inheritance requires
flattening those authored definitions or making a separate upstream change.
inheritance. Use existing local sibling inheritance for this development round;
applications can still select the qualified `provider/brief` profile directly.
Authors needing a customized derivative may publish an expanded definition.
Expansion is a migration option, not a mandatory authoring workflow.
An alternative is generic explicit-path inheritance in ConfigKit, with its own
syntax, cycle rules, and provenance contract. That would preserve reusable
cross-collection bases, but crosses a currently deferred ConfigKit boundary
and is additional work beyond mounting. PromptKit must not resolve such
relationships itself after handoff. Decide whether this capability is required
before selecting a migration plan.
Generic cross-path inheritance remains possible future ConfigKit work if a
concrete consumer need justifies it. It is not a prerequisite of this round.
PromptKit must not add its own inheritance resolver after ConfigKit handoff.
## Specification Versions And Collection Inventory
@@ -341,20 +349,21 @@ before selecting a migration plan.
Use one `Definition.Version` policy, with source-local path `version`, for the
candidate PromptKit specification. Initially accept specification text `1` from
string or strict decimal-integer declarations; reject explicit null and other
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
unsupported declarations through the ConfigKit checker. Accept an absent main
declaration, including an absent main input. 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 retired proposals were alternatives, not released formats
sharing specification version 1.
The selected initial direction is `SourceVersionModeIfPresent`:
Use `SourceVersionModeIfPresent` without adding a PromptKit mode-selection
option in this round. A stricter option can be considered for a demonstrated
consumer need. The upstream modes remain distinct:
| Mode | Implemented behavior | Role in this proposal |
| --- | --- | --- |
| `Default` | Existing main-only effective-path check and protected-path behavior | Not the proposed shared-source policy |
| `IfPresent` | Checks present declarations; skips absent non-main declarations | Initial choice for compact fragments |
| `Required` | Requires declarations on every participating document | Possible stricter consumer option; not entry-only checking |
| `Required` | Requires declarations on every participating document | Upstream capability; exposing a PromptKit option is deferred |
Participating documents include actual main and underlay inputs, transitive and
glob imports, and the selected overlay. Defaults, synthetic CLI overrides,
@@ -370,9 +379,12 @@ Do not confuse header consumption with permission to override the remaining
protected application field.
`IfPresent` does not require a collection entry header and does not infer a
fragment's compatibility from its entry. It checks the declarations actually
present. Requiring headers only on entry files is not supported by the load-wide
mode. Do not emulate it using a preliminary manifest load or validation of
fragment's compatibility from its entry. A publisher can declare compatibility
in the entry while leaving imported files headerless; the assembled configuration
still undergoes normal validation. A declaration is not a guarantee of future
compatibility or independent schema validation of every imported fragment.
ConfigKit checks the declarations actually present. Requiring headers only on
entry files is not supported by the load-wide mode. Do not emulate it using a preliminary manifest load or validation of
source history. If that stronger guarantee becomes essential, seek an explicit
upstream contract instead.
@@ -387,20 +399,17 @@ Migration must rename it rather than simply enable the new mode.
This reservation affects resource fragments whose local key is literally
`version`: a root mapping with that name is interpreted as a malformed header.
Recommend expressing such a resource within a nested resource mapping in the
collection entry, for example `prompts: {version: ...}`, rather than globally
banning that public resource ID. The exact author-facing convention remains
open below. Existing `configkit` and `extends` structural reservations also
remain applicable; destinations do not bypass them.
Allow that resource name through a nested resource mapping, for example
`prompts: {version: ...}` in a collection entry. Reserve the header position,
not the public resource name. Existing `configkit` and `extends` structural
reservations also remain applicable; destinations do not bypass them.
An absent header in an actual main document still reaches the checker under
`IfPresent`. `NoSource` also invokes the existing absent-main checker behavior,
even under `Required`. Consequently, the mode alone does not determine whether
PromptKit supports construction without a main declaration. Recommend an
explicit main specification declaration for the new standard, including for a
programmatically supplied main, without silently injecting one. An alternative
is to accept absent main declarations deliberately for underlay-only callers;
settle that compatibility choice before implementing the checker.
`IfPresent`; `NoSource` invokes the absent-main checker as well. PromptKit's
checker accepts omission in both cases. Consumers may assemble only underlays,
fragments, or programmatic inputs without manufacturing a main document or
header. Do not inject a declaration or report undeclared sources as checked.
Present unsupported declarations still fail; final schema validation still runs.
### Inspection And Effective Collection Inventory
@@ -446,19 +455,20 @@ Proposal 2's generic extension is preserved in the ConfigKit repository as
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.
prerequisite of this roadmap. The subsequently accepted PromptKit decisions
are recorded below.
## Migration
Migration must choose one installed definition for each former multi-version
prompt, move any retained version into its optional field, and relocate
qualified resource keys into collection/local-key mappings. Update destination
declarations, stored references, request-version handling, inventories, and
configuration-inspection paths. Rename collection release metadata to
declarations, stored references, inventories, and configuration-inspection paths. Rename collection release metadata to
`release_version`, configure the shared checker and mode, and account for the
source-root header reservation and the selected main-absence policy. Preserve
provider model strings and source resource bases. Namespace mounting does not
source-root header reservation and optional main declarations. Remove obsolete
request-version fields and version-selection logic from consumer examples and
public APIs rather than retaining them as assertions. Preserve provider model
strings and source resource bases. Namespace mounting does not
automatically relocate schema or artifact stores or rewrite references when a
collection is renamed.
@@ -481,9 +491,10 @@ PromptKit acceptance should exercise typed assembly of multiple collections,
relative/nested imports, source-local header checking and consumption, ordinary
release and prompt metadata, unqualified resources, scoped selection, optional
prompt versions, inventory without release metadata, source-relative content,
intentional partial overrides, and the chosen main-absence policy. Add request
version assertions if retained. Do not duplicate ConfigKit's generic source
validation or enforce domain rules through historical source inspection.
intentional partial overrides, headerless entries/fragments, omitted main inputs
and headers, and resources named `version` in nested mappings. Verify ID-only
lookup and descriptive labels without version selection or request assertions.
Do not duplicate ConfigKit's generic source validation or enforce domain rules through historical source inspection.
Review verification on 2026-10-16 against ConfigKit `e66c371`: focused public API
and consumer-example tests passed. A temporary typed consumer also passed
@@ -496,41 +507,35 @@ fragments through entry imports and matched the illustrated effective tree;
local links and whitespace checks passed. These checks verify upstream behavior
and the candidate schema, not an implemented PromptKit engine feature.
## Remaining PromptKit Decisions
## Accepted Configuration Decisions
The agreed direction uses the implemented mount/import APIs, a shared
specification policy with `IfPresent`, and distinct `release_version` metadata.
These are no longer pending upstream feature requests. The following choices
remain before the PromptKit contract is complete:
The following decisions settle the six questions previously listed here:
1. **Main declaration:** recommend requiring an explicit supported declaration
in a real or programmatic main input. Alternatively, accept absent main for
existing underlay-only callers, with the weaker guarantee documented. Neither
option follows automatically from ConfigKit's mode, and no version should be
silently injected.
2. **Public mode selection:** use `IfPresent` initially. Decide whether callers
may opt into `Required` through PromptKit's source configuration API. Exposing
it gives deployments an all-document declaration requirement; keeping one
initial mode reduces API surface. It cannot mean entry-only enforcement.
3. **Reserved header naming:** recommend allowing a local resource ID `version`
through nested mappings in the entry document while reserving source-root
`version` for the specification. Alternatively, reserve that resource name
in the new format for a uniform fragment convention, at the cost of a new ID
restriction. Do not let an incidental parser limitation silently decide it.
4. **Request versions:** recommend retaining optional exact assertions against
the one installed prompt's label. Removing request-side version fields is
simpler if consumers do not need this compatibility guard. Also finalize the
proposed absent/null/nonblank-string rules and listing representation.
5. **Cross-collection inheritance:** recommend local sibling inheritance and
flattening authored cross-collection bases for the initial migration.
Request generic cross-path inheritance upstream only if concrete catalog
migration needs justify it; do not resolve it inside PromptKit.
6. **Consumer API and packaging:** recommend an explicitly selected entry path
and namespace, with publisher-owned relative imports and one peer group.
Finalize the helper signatures, conventional entry filename, inventory types,
and migration examples. Direct mounted fragments remain a useful alternative
for applications that already assemble sources themselves.
1. **Main declaration:** optional, including for programmatic or underlay-only
construction. Validate supplied declarations without injecting missing ones.
2. **Public mode selection:** use `IfPresent`; defer a stricter PromptKit option
until a consumer need justifies it. No per-file header requirement.
3. **Reserved header naming:** reserve source-root `version`, while allowing a
resource named `version` through a nested resource mapping.
4. **Request versions:** remove request-side version fields and selection
machinery. Retain optional descriptive prompt labels only.
5. **Cross-collection inheritance:** use current ConfigKit inheritance; direct
profile references and authored expansion remain available. Defer a generic
upstream extension without adding a PromptKit resolver.
6. **Consumer API and packaging:** provide a small source/namespace convenience
API; recommend entry files and relative imports without requiring a filename,
layout, main input, or single peer group. Preserve direct fragment loading,
programmatic sources, and consumer-controlled precedence. Inventory reports
effective collections with optional release metadata.
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.
## Remaining Delivery Details
No unresolved configuration-policy decision remains from those six questions.
Implementation still needs to select a released ConfigKit dependency containing
the required capabilities, finalize helper signatures and inventory/optional-label
representations, and provide migration examples. These are delivery details,
not reasons to introduce additional workflows or speculative API options.
Stricter header modes and cross-path inheritance are deferred capabilities, not
implementation prerequisites. Update current contracts when behavior lands;
this roadmap records future work and does not itself implement the feature.