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

Align collection proposal with implemented ConfigKit capabilities

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-16 11:51:18 +00:00
parent c7490b783b
commit b5866dd749
2 changed files with 270 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,18 +1,20 @@
# Proposal 3: Collections With Mounted Configuration Fragments # Proposal 3: Collections With Mounted Configuration Fragments
Status: proposed alternative; not implemented. The authoring direction follows Status: proposed PromptKit standard; not implemented in PromptKit. Required
the discussion's preference for collection-local mapping keys, one installed ConfigKit capabilities are implemented on its development branch, reviewed at
definition per prompt, and an optional flat prompt `version` field. The overall `e66c371` on 2026-10-16, but are not in PromptKit's selected v0.7.1 dependency.
configuration standard and upstream API still require selection. Compare 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 1](configuration-collections-current-configkit.md) and
[proposal 2](configuration-collections-identified-records.md); the parent [proposal 2](configuration-collections-identified-records.md); the parent
[namespace roadmap](namespaces.md) owns the shared decisions. [namespace roadmap](namespaces.md) owns the shared decisions.
## Recommendation ## Recommendation
Ask ConfigKit to support an explicit destination path for configuration inputs. Use ConfigKit's implemented input destinations and relative import destinations.
For example, inputs selected from a collection's `prompts` directory would For example, a collection entry can import its `prompts` directory beneath
contribute their document bodies beneath the literal configuration path
`[collections, weatherreporter, prompts]`. Authors write local prompt names and `[collections, weatherreporter, prompts]`. Authors write local prompt names and
definitions without repeating either `prompts:` or the namespace in each file. definitions without repeating either `prompts:` or the namespace in each file.
@@ -30,28 +32,36 @@ Placement belongs to ConfigKit. PromptKit must not parse, wrap, or rewrite each
source itself, nor impose duplicate-namespace checks before composition. This source itself, nor impose duplicate-namespace checks before composition. This
preserves the accepted [configuration boundary](../adr/0001-configuration-boundary.md). preserves the accepted [configuration boundary](../adr/0001-configuration-boundary.md).
## Current Baseline And Required Extension ## Reviewed Upstream Capabilities And Adoption Status
The reviewed ConfigKit checkout is v0.7.1, commit The reviewed ConfigKit development checkout is `e66c371`. Its public
`6fffde4af8f31f99d3ee295c426eb3234cb0fb77`, also the dependency selected by configuration contract (`docs/config.md`, sections “Input destinations” and
PromptKit. Its [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/config.md) “Shared source-version checks”) and ADRs 0011–0013 own the upstream behavior.
and public `Input` declaration establish the relevant baseline: PromptKit still selects ConfigKit v0.7.1; choose a released dependency containing
these capabilities before implementation. This roadmap does not imply they are
already available through PromptKit or select an upstream release number.
- Inputs select a source, import policy, and filesystem context. They do not The implemented public surface provides:
expose a destination in the effective configuration tree.
- YAML documents have mapping roots. Strict composition recursively combines
mappings and rejects every overlapping non-mapping pair, even equal values.
- Explicit precedence layers recursively overlay mappings; scalar, sequence,
and null values replace lower values. File order does not confer precedence.
- `extends` names an immediate mapping sibling and resolves after assembly.
- The configured specification-version path is checked on main only and
protected against contributions from fragments and lower layers.
- Effective fields retain source origins and filesystem resource contexts.
The collection-shaped tree can be authored explicitly with current ConfigKit. - `Input.Destination` for root-relative placement, and YAML import
Removing the repeated wrappers from source files requires the proposed mount `destination: [prompts]` for placement relative to the immediate importing
capability. PromptKit also needs a new schema and runtime indexing changes; document. Glob matches share the declared destination; nested imports append
none of the proposed PromptKit examples are supported by its current schema. to their immediate parent's destination.
- `Options.SourceVersionMode` and `LayeredOptions.SourceVersionMode`, using one
shared `Definition.Version` rule. Enabled modes interpret the rule's path in
each document's source-local coordinates before placement and composition.
- Consumption of accepted non-main specification headers, with the main header
retained and protected at its effective application path.
- `SourceInfo.Destination` and `SourceInfo.VersionCheck` for detached inspection
evidence, alongside existing source locations and resource contexts.
Strict mapping composition, explicit precedence, atomic sequences, and local
sibling inheritance retain their existing rules. ConfigKit owns the complete
load; PromptKit interprets and validates final effective values. No further
ConfigKit extension is required for the initial direction described here.
The new PromptKit schema and runtime indexes remain future work. The existing
[format reference](../formats.md) remains authoritative until adoption.
## Authoring And Assembly ## Authoring And Assembly
@@ -99,46 +109,68 @@ default:
endpoint: https://inference.example.invalid/v1 endpoint: https://inference.example.invalid/v1
``` ```
An optional `weatherreporter/collection.yml` contributes collection metadata: A conventional `weatherreporter/collection.yml` entry can declare the shared
specification, optional collection release, and its layout:
```yaml ```yaml
version: "2.4.0" version: 1
release_version: "2.4.0"
configkit:
imports:
- glob: prompts/*.yml
destination: [prompts]
``` ```
Here that field is a collection release label because the document is mounted A provider entry can import `profiles/*.yml` at `[profiles]` and
at the collection node. It is not a PromptKit specification declaration. Keep `backends/*.yml` at `[backends]` in the same way. Collection publishers choose
these two uses explicit in author documentation and packaging examples. which categories to include. A required glob must match; unused categories can
be omitted or use ConfigKit's existing optional-import behavior. Ordinary
fragments may omit specification headers under the selected `IfPresent` mode.
An entry header is the recommended publishing convention, not a load-time
requirement selectively enforced on entries by this mode.
The consuming application's source selection would express placements like The application selects each entry, enables its imports, and supplies its
these. Paths are illustrative; the destination column is a list of literal namespace through the public input destination. For example, the following
mapping keys, not a slash-delimited string or proposed API syntax. partial Go snippet uses implemented ConfigKit development-branch APIs:
| Selected source | Destination | ```go
entry := configkit.Input{
Source: configkit.File("/usr/local/share/collections/weatherreporter/collection.yml"),
Imports: true,
Destination: configkit.Keys("collections", "weatherreporter"),
}
```
Put peer collection entries into one `Underlay` group's `Inputs`. 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.
| Selected source | Effective destination |
| --- | --- | | --- | --- |
| Application main document | `[]` (configuration root) | | Application main document | Configuration root |
| `weatherreporter/collection.yml` | `[collections, weatherreporter]` | | `weatherreporter/collection.yml` | `[collections, weatherreporter]` |
| YAML fragments under `weatherreporter/prompts` | `[collections, weatherreporter, prompts]` | | Its `prompts/*.yml` imports | `[collections, weatherreporter, prompts]` |
| YAML fragments under `homewatch/prompts` | `[collections, homewatch, prompts]` | | Homewatch entry and its prompt imports | `[collections, homewatch]` and `[collections, homewatch, prompts]` |
| YAML fragments under `provider/profiles` | `[collections, provider, profiles]` | | Provider entry and its profile/backend imports | `[collections, provider]`, then `[profiles]` or `[backends]` appended |
| YAML fragments under `provider/backends` | `[collections, provider, backends]` |
The namespace is supplied by the assembly declaration. A collection-selection Directly selected fragments with `Input.Destination` remain possible. Entry
helper could take it once and construct these destinations for conventional imports are the recommended packaging convention because publishers can describe
subdirectories without reading or transforming document contents. ConfigKit their layout. Filenames and directory basenames do not define resource identity;
would still perform all placement and composition. Directory basenames do not no implicit directory discovery, namespace inference, or collection installer is
implicitly identify namespaces, and filenames do not identify resources. introduced. A helper may construct inputs from explicit source selections but
must not inspect manifests to compute their destinations.
Recommend explicit source selection through the ConfigKit input API first. Use later underlay groups or main for intentional application/operator overrides.
PromptKit's directory helpers can enumerate files and attach a destination to Placement does not establish precedence. Do not also recursively scan files
each input once that API exists. A YAML import destination could expose the already selected by entry imports: ConfigKit's repeated-source rules still apply.
same operation later or alongside it; its concrete spelling is an upstream
decision. This proposal does not claim that existing `configkit.imports`
directives accept a destination today.
Put peer collection inputs in one strict underlay group. Use later groups or The entry's source-root `version` is checked and consumed before its payload
main for intentional application/operator overrides. Selecting a destination composes. Its `release_version` is retained as ordinary collection metadata.
does not select a precedence tier. Avoid loading the same files both through A prompt's nested optional `version` is also ordinary payload. These are three
a recursive whole-collection scan and through the individual mounted folders. distinct concepts; source-root release metadata must no longer use `version`.
The assembled application shape would be equivalent to: The assembled application shape would be equivalent to:
@@ -146,7 +178,7 @@ The assembled application shape would be equivalent to:
version: 1 version: 1
collections: collections:
weatherreporter: weatherreporter:
version: "2.4.0" release_version: "2.4.0"
prompts: prompts:
summarize.alerts: summarize.alerts:
version: "1" version: "1"
@@ -185,15 +217,16 @@ it is not a PromptKit resource identifier.
One fragment may contain several local definitions. A fragment starting directly One fragment may contain several local definitions. A fragment starting directly
with `messages:` would need a destination that also supplies the local prompt with `messages:` would need a destination that also supplies the local prompt
key. Generic mounting could permit that, but recommend the local-key mapping key. ConfigKit mounting permits such placement, but with source checks enabled
above as the standard authoring form: identity travels with the definition and its root `version` would be the specification header, not prompt metadata. Recommend
files may be reorganized without changing it. Filename-derived IDs are not the local-key mapping above as the standard authoring form: identity travels
with the definition and files may be reorganized without changing it. Filename-derived IDs are not
needed. needed.
## Final Schema And Identity ## Final Schema And Identity
Recommend `collections` as a mapping of namespace to collection body, containing Recommend `collections` as a mapping of namespace to collection body, containing
optional release `version` and optional `backends`, `profiles`, and `prompts` optional `release_version` and optional `backends`, `profiles`, and `prompts`
mappings. Collection release labels are descriptive, with no SemVer ordering mappings. Collection release labels are descriptive, with no SemVer ordering
or dependency-solving semantics. Metadata is optional: an installed collection or dependency-solving semantics. Metadata is optional: an installed collection
can contain resources without claiming a published release. can contain resources without claiming a published release.
@@ -244,47 +277,27 @@ Proposals 1 and 2 retain their earlier assumptions for comparison. The parent
roadmap's version-selection and listing language needs corresponding revision roadmap's version-selection and listing language needs corresponding revision
if proposal 3 is adopted. if proposal 3 is adopted.
## Required ConfigKit Mount Semantics ## ConfigKit Composition Boundary
The upstream feature should be generic source placement, not a PromptKit-aware Use the implemented upstream contracts without duplicating them in PromptKit.
collection loader or application callback that transforms source documents. Input destinations use literal mapping-key segments, independent of filesystem
The following is the recommended contract to agree and test upstream: roots and precedence. Relative import destinations are sequences of strings;
omission and `[]` retain the importing destination. Null, scalar, and non-string
destination members are invalid. No logical path segment means parent traversal
or a reset to the application root.
1. An input has an optional destination of literal mapping-key segments. An Source-root import directives remain structural. Imported content contributes at
empty destination preserves existing root behavior. It is independent of its resulting destination, while physical import paths and `content_file` bases
the filesystem path, filesystem containment root, and precedence group. remain relative to their declaring sources. `SourceInfo.Destination` records
2. ConfigKit parses each source with its existing YAML rules and processes placement; normal origins and diagnostics retain real source locations. Selected
source-root directives before placing application content at its destination. overlays and explicit CLI overrides remain rooted at the application root.
Synthetic mapping ancestors participate in ordinary composition. It does
not turn dots or slashes inside a generic key into path separators.
3. Imports without an explicit destination inherit the importing input's
destination. If import placement is exposed, recommend its destination be
relative to the importing destination. Explicitly selected independent
inputs use root-relative destinations. This keeps a mounted import subtree
contained in its declared configuration context without guessing filenames.
4. Placement precedes strict composition and layer assembly. Contributions to
the same destination obey the existing mapping rules; conflicts with scalar
ancestors use those same strict-versus-overlay rules. No new merge, deletion,
or whole-definition replacement operation is implied.
5. Origins and diagnostics retain physical source locations and explain their
effective destination paths. Synthesized ancestors must not obscure the
contributing source. Resource contexts remain attached to the declaring
source: mounting does not relocate relative `content_file` references.
6. Apply protected specification-path checks to the destination-adjusted
application paths. A release `version` mounted at
`[collections, weatherreporter]` is not the protected root `version`.
Contributions that actually reach or replace the protected path remain
forbidden. Main's version checker still runs at its established stage;
mounting does not grant fragments their own compatibility checks.
7. Preserve source cycle/repetition, acquisition, and budget rules. Mounting
must not silently authorize loading the same physical source twice within
a group. Account for synthesized ancestors and destination depth within
ConfigKit's limits. Existing unmounted loads retain their behavior.
Item 6 is a necessary upstream change, not something PromptKit can work around Mounting preserves source identity, cycle/repetition rules, and load limits.
by stripping a source header. Agree its interaction with imports and main's An absent `NoSource` contributes no payload; an actual empty mapping can
version protection explicitly. Mounting main away from the root is unnecessary materialize its destination containers without clearing lower contents.
for this PromptKit standard. ConfigKit's reserved structural keys continue to apply. PromptKit must not
strip headers, re-key source trees, merge fragments itself, or turn source
inspection into an additional enforcement pass.
### Composition And Overrides ### Composition And Overrides
@@ -324,32 +337,92 @@ before selecting a migration plan.
## Specification Versions And Collection Inventory ## Specification Versions And Collection Inventory
Keep `version: 1` at the application root for the candidate PromptKit ### Shared Specification Policy
specification, checked through ConfigKit's version mechanism. It describes
the assembled schema, independently of collection release and prompt labels.
The three proposals are competing candidate formats, not interchangeable
released meanings of specification version 1.
Mounting alone does not solve independent collection compatibility checking. Use one `Definition.Version` policy, with source-local path `version`, for the
A mounted `collection.yml` containing a release `version` does not declare or candidate PromptKit specification. Initially accept specification text `1` from
validate a separate specification version. A self-contained collection entry string or strict decimal-integer declarations; reject explicit null and other
document with its own specification header would need a further ConfigKit unsupported declarations through the ConfigKit checker. The handling of an
contract for checking and consuming that header before mounting its payload. absent main declaration remains an explicit decision below. Accept additional
Do not infer compatibility from a directory name or release label, or have versions only when PromptKit actually supports their format semantics: accepting
PromptKit load and validate each manifest separately. Keep that upstream a header does not migrate its payload or independently validate a fragment's
extension open rather than bundling it implicitly into source placement. complete schema. The three proposals are alternative candidate formats, not
interchangeable released meanings of specification version 1.
Recommend collection inventory derived from the final `collections` mapping: The selected initial direction is `SourceVersionModeIfPresent`:
namespace plus optional effective release label, sorted and detached from the
captured engine. Metadata-only and resource-only entries can both appear.
Root unqualified resources do not invent a named collection. Resource-based
namespace enumeration remains a separate listing operation.
An inventory reports effective configuration declarations, not immutable | Mode | Implemented behavior | Role in this proposal |
package identity, historical source ownership, or proof of unchanged published | --- | --- | --- |
contents. Operator overrides may alter resources while leaving a release | `Default` | Existing main-only effective-path check and protected-path behavior | Not the proposed shared-source policy |
label in place. Source explanations remain ConfigKit inspection concerns. | `IfPresent` | Checks present declarations; skips absent non-main declarations | Initial choice for compact fragments |
Engine construction captures configuration; edits require a replacement engine. | `Required` | Requires declarations on every participating document | Possible stricter consumer option; not entry-only checking |
Participating documents include actual main and underlay inputs, transitive and
glob imports, and the selected overlay. Defaults, synthetic CLI overrides,
resolution output, absent optional imports, and empty groups do not need headers.
Explicit null is present and reaches the checker; malformed selected values
fail ConfigKit's version-type validation. A rejected declaration fails loading
even if a higher layer would supersede that source's payload.
In enabled modes, accepted non-main headers are consumed before composition.
The main declaration remains and is protected at its destination-prefixed path.
PromptKit's recommended main is unmounted, so that protected path is `/version`.
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
source history. If that stronger guarantee becomes essential, seek an explicit
upstream contract instead.
### Naming And Optional Main Inputs
Reserve source-root `version` for specification declarations throughout the new
format. Use `release_version` for optional collection release labels and retain
nested prompt `version` for the optional installed-prompt label. An old release
file containing only `version: "2.4.0"` can fail the specification check; if its
text happens to be accepted, that field is consumed and lost as release metadata.
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.
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.
### Inspection And Effective Collection Inventory
`SourceInfo.VersionCheck` is source evidence, not a generic success flag. A
non-nil record with `Present == false` can describe an omission for which the
checker did not run. Header paths and locations are source-local. Evidence is
detached and does not reread inputs; text is conservatively redacted during
callbacks and on failed loads, and successful final records respect completed
sensitivity classification. These records belong in explicit configuration
inspection, not in ordinary domain validation or collection-release identity.
Derive collection inventory from the final `collections` mapping: namespace
plus optional effective `release_version`, sorted and detached from the captured
engine. Metadata-only and resource-only entries can both appear. Root unqualified
resources do not invent a named collection; resource-based namespace enumeration
remains separate. Exact exported inventory types remain API design work.
An inventory describes effective configuration, not immutable package identity,
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 ## Comparison And Migration
@@ -360,10 +433,11 @@ Engine construction captures configuration; edits require a replacement engine.
| Multiple installed versions per prompt | Supported | Supported | Not supported | | Multiple installed versions per prompt | Supported | Supported | Not supported |
| Repeated resource wrapper in fragments | Required | Required | Omitted through placement | | Repeated resource wrapper in fragments | Required | Required | Omitted through placement |
| Composition machinery | Existing mappings | Identified record sequences | Existing mappings after placement | | Composition machinery | Existing mappings | Identified record sequences | Existing mappings after placement |
| Main upstream change | None | Record composition and inheritance | Source placement, provenance, and adjusted path protection | | 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 | | Cross-collection inheritance | Existing qualified sibling keys | Proposed tuple references | Requires a separate extension or authored flattening |
| Independent collection specification check | Unavailable | Unavailable | Still a separate extension | | Source specification checks as described | Main only | Main only | Shared policy; non-main declarations checked when present |
Proposals 1 and 2 retain their original assumptions for historical comparison.
Proposal 3 is the recommended direction for the stated one-installed-prompt Proposal 3 is the recommended direction for the stated one-installed-prompt
requirement. Its authoring economy follows from the configuration hierarchy, requirement. Its authoring economy follows from the configuration hierarchy,
and it retains ordinary map composition. The tradeoffs are explicit assembly and it retains ordinary map composition. The tradeoffs are explicit assembly
@@ -374,9 +448,12 @@ Migration must choose one installed definition for each former multi-version
prompt, move any retained version into its optional field, and relocate prompt, move any retained version into its optional field, and relocate
qualified resource keys into collection/local-key mappings. Update destination qualified resource keys into collection/local-key mappings. Update destination
declarations, stored references, request-version handling, inventories, and declarations, stored references, request-version handling, inventories, and
configuration-inspection paths. Preserve provider model strings and source configuration-inspection paths. Rename collection release metadata to
resource bases. Namespace mounting does not automatically relocate schema or `release_version`, configure the shared checker and mode, and account for the
artifact stores or rewrite references when a collection is renamed. source-root header reservation and the selected main-absence policy. 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.
Retain the accepted removal of mandatory catalog modules and built-in profiles. Retain the accepted removal of mandatory catalog modules and built-in profiles.
This is a breaking configuration/API change under the This is a breaking configuration/API change under the
@@ -384,50 +461,70 @@ This is a breaking configuration/API change under the
migration guidance and update current contracts when it lands. The proposal migration guidance and update current contracts when it lands. The proposal
does not change today's supported configuration or API. does not change today's supported configuration or API.
## Delivery, Validation, And Remaining Decisions ## Delivery And Validation
Agree and implement the generic mount contract in ConfigKit first, then adopt Select a released ConfigKit dependency containing the reviewed capabilities,
it in PromptKit's source helpers and final-configuration adapter. Build qualified then implement PromptKit's schema, source-selection convenience APIs, and final
runtime indexes only after handoff. Keep collection installation, remote configuration adapter. Do not use a committed filesystem replacement as the
fetching, automatic directory discovery, live reload, and dependency solving release integration. Build qualified runtime indexes after handoff. Collection
outside this work. installation, remote fetching, implicit discovery, live reload, identity-based
list composition, and dependency solving remain outside this work.
Upstream acceptance should exercise root and nested placement; overlapping PromptKit acceptance should exercise typed assembly of multiple collections,
destinations within strict groups and across layers; mounted nested imports; relative/nested imports, source-local header checking and consumption, ordinary
source cycles/repetition; destination-aware protected-version checks; source release and prompt metadata, unqualified resources, scoped selection, optional
locations and resource bases; sibling inheritance; and unchanged unmounted prompt versions, inventory without release metadata, source-relative content,
behavior. Verify mounted metadata cannot bypass root version protection. 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.
PromptKit acceptance should cover the illustrated assembled tree, same local Review verification on 2026-10-16 against ConfigKit `e66c371`: focused public API
names in different collections, unqualified resources, scoped selection, and consumer-example tests passed. A temporary typed consumer also passed
versioned and unversioned prompts, explicit version assertions if retained, combined assembly for two collections with equal local prompt names, nested
inventory without release metadata, source-relative message content, and relative imports and content-file contexts, optional prompt versions, both
intentional partial overrides. Do not add per-source PromptKit validation. enabled header modes, rejected headers despite upper-layer overrides, and
migration behavior for old release fields. The temporary consumer lives outside
both repositories. An additional offline check assembled this document's YAML
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.
Review verification on 2026-10-14: a temporary offline consumer of the local ## Remaining PromptKit Decisions
ConfigKit checkout decoded all six YAML examples into generic mappings and
confirmed that a version-only overlay preserves the lower prompt body. Local
documentation links and whitespace checks passed. These checks establish the
current YAML and mapping behavior, not the unimplemented mount extension or
future PromptKit schema. The temporary consumer is outside both repositories.
The remaining decisions are: 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:
- **Mount API and packaging:** prefer an input destination plus a conventional 1. **Main declaration:** recommend requiring an explicit supported declaration
explicitly selected directory layout. An import-destination directive would in a real or programmatic main input. Alternatively, accept absent main for
let publishers express more assembly in configuration; settle its syntax existing underlay-only callers, with the weaker guarantee documented. Neither
upstream. A manifest that computes its own mount from a declared namespace option follows automatically from ConfigKit's mode, and no version should be
would require further ConfigKit semantics and is not assumed here. silently injected.
- **Cross-collection inheritance:** prefer existing local sibling inheritance 2. **Public mode selection:** use `IfPresent` initially. Decide whether callers
initially; add generic path references upstream if migration needs justify may opt into `Required` through PromptKit's source configuration API. Exposing
the added contract. it gives deployments an all-document declaration requirement; keeping one
- **Request versions:** prefer optional exact assertions for migration; removing initial mode reduces API surface. It cannot mean entry-only enforcement.
version selectors is simpler if consumers do not need that guard. 3. **Reserved header naming:** recommend allowing a local resource ID `version`
- **Independent specification headers:** keep one main-owned declaration for through nested mappings in the entry document while reserving source-root
this proposal; pursue a distinct ConfigKit extension if collections must `version` for the specification. Alternatively, reserve that resource name
each assert compatibility independently. 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.
These recommendations are reviewable choices, not claims that upstream work The parent roadmap still owns the overall configuration decision. Its older
has been accepted. One installed definition and an optional prompt version are version-selection and metadata examples describe earlier alternatives; adopting
the settled requirements for this alternative. The parent configuration this standard requires reconciling those details and updating current contracts
decision remains open while the three proposals are compared. when implementation lands.

11
docs/roadmap/namespaces.md
View File

@@ -492,10 +492,13 @@ uses an opt-in upstream extension for identity-based record composition and
inheritance. [Proposal 3: mounted fragments](configuration-collections-mounted-fragments.md) inheritance. [Proposal 3: mounted fragments](configuration-collections-mounted-fragments.md)
uses explicit upstream source placement and collection-local mapping keys, uses explicit upstream source placement and collection-local mapping keys,
with one installed definition per prompt and an optional flat version field. with one installed definition per prompt and an optional flat version field.
All three retain main-owned specification versioning; independent collection Proposal 3 now targets implemented ConfigKit development-branch capabilities,
checks remain a separate upstream question. These are proposals for comparison; including relative imports and shared source-version checks with `IfPresent`. It
this decision remains open. Proposal 3 deliberately revises the version-selection uses `release_version` for collection metadata; proposals 1 and 2 preserve their
and listing assumptions elsewhere in this roadmap if that alternative is adopted. earlier baselines for comparison. This overall decision remains open. Proposal 3
deliberately revises the version-selection, metadata, and listing assumptions
elsewhere in this roadmap if that alternative is adopted. Its remaining questions
are PromptKit policy/API choices, not pending requests for those ConfigKit features.
**Desired capability:** describe collection namespace and release version in **Desired capability:** describe collection namespace and release version in
configuration and expose an API through which downstream applications can list configuration and expose an API through which downstream applications can list