promptkit/docs/roadmap/configuration-collections-mounted-fragments.md

Proposal 3: Collections With Mounted Configuration Fragments

Status: proposed alternative; not implemented. The authoring direction follows the discussion's preference for collection-local mapping keys, one installed definition per prompt, and an optional flat prompt version field. The overall configuration standard and upstream API still require selection. Compare proposal 1 and proposal 2; the parent namespace roadmap owns the shared decisions.

Recommendation

Ask ConfigKit to support an explicit destination path for configuration inputs. For example, inputs selected from a collection's prompts directory would contribute their document bodies beneath the literal configuration path [collections, weatherreporter, prompts]. Authors write local prompt names and definitions without repeating either prompts: or the namespace in each file.

Use a collection-shaped effective configuration. Each collection contains its release metadata and ordinary mappings of backends, profiles, and prompts. PromptKit derives qualified public IDs from the final collection and resource 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.

Placement belongs to ConfigKit. PromptKit must not parse, wrap, or rewrite each source itself, nor impose duplicate-namespace checks before composition. This preserves the accepted configuration boundary.

Current Baseline And Required Extension

The reviewed ConfigKit checkout is v0.7.1, commit 6fffde4af8f31f99d3ee295c426eb3234cb0fb77, also the dependency selected by PromptKit. Its configuration contract and public Input declaration establish the relevant baseline:

• Inputs select a source, import policy, and filesystem context. They do not 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. Removing the repeated wrappers from source files requires the proposed mount capability. PromptKit also needs a new schema and runtime indexing changes; none of the proposed PromptKit examples are supported by its current schema.

Authoring And Assembly

A file such as weatherreporter/prompts/alerts.yml would contain:

summarize.alerts:
  version: "1"
  default_profile: provider/brief
  messages:
    - role: user
      content: Summarize the weather alerts.
  output:
    format: text
    validation_mode: none

The version may simply be omitted. Another collection can contribute the same local prompt name, for example homewatch/prompts/alerts.yml:

summarize.alerts:
  default_profile: provider/brief
  messages:
    - role: user
      content: Summarize the household alerts.
  output:
    format: text
    validation_mode: none

A provider collection's profiles/brief.yml uses the same local-key convention:

brief:
  backend: provider/default
  model: vendor/example-model
  temperature: 0.2

Its backends/default.yml could contain this synthetic, non-live endpoint:

default:
  endpoint: https://inference.example.invalid/v1

An optional weatherreporter/collection.yml contributes collection metadata:

version: "2.4.0"

Here that field is a collection release label because the document is mounted at the collection node. It is not a PromptKit specification declaration. Keep these two uses explicit in author documentation and packaging examples.

The consuming application's source selection would express placements like these. Paths are illustrative; the destination column is a list of literal mapping keys, not a slash-delimited string or proposed API syntax.

Selected source	Destination
Application main document	[] (configuration root)
weatherreporter/collection.yml	[collections, weatherreporter]
YAML fragments under weatherreporter/prompts	[collections, weatherreporter, prompts]
YAML fragments under homewatch/prompts	[collections, homewatch, prompts]
YAML fragments under provider/profiles	[collections, provider, profiles]
YAML fragments under provider/backends	[collections, provider, backends]

The namespace is supplied by the assembly declaration. A collection-selection helper could take it once and construct these destinations for conventional subdirectories without reading or transforming document contents. ConfigKit would still perform all placement and composition. Directory basenames do not implicitly identify namespaces, and filenames do not identify resources.

Recommend explicit source selection through the ConfigKit input API first. PromptKit's directory helpers can enumerate files and attach a destination to each input once that API exists. A YAML import destination could expose the 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 main for intentional application/operator overrides. Selecting a destination does not select a precedence tier. Avoid loading the same files both through a recursive whole-collection scan and through the individual mounted folders.

The assembled application shape would be equivalent to:

version: 1
collections:
  weatherreporter:
    version: "2.4.0"
    prompts:
      summarize.alerts:
        version: "1"
        default_profile: provider/brief
        messages:
          - role: user
            content: Summarize the weather alerts.
        output:
          format: text
          validation_mode: none
  homewatch:
    prompts:
      summarize.alerts:
        default_profile: provider/brief
        messages:
          - role: user
            content: Summarize the household alerts.
        output:
          format: text
          validation_mode: none
  provider:
    backends:
      default:
        endpoint: https://inference.example.invalid/v1
    profiles:
      brief:
        backend: provider/default
        model: vendor/example-model
        temperature: 0.2

This yields weatherreporter/summarize.alerts and homewatch/summarize.alerts, plus profile provider/brief and backend provider/default. The provider's model string remains vendor/example-model; it is not a PromptKit resource identifier.

One fragment may contain several local definitions. A fragment starting directly with messages: would need a destination that also supplies the local prompt key. Generic mounting could permit that, but recommend 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.

Final Schema And Identity

Recommend collections as a mapping of namespace to collection body, containing optional release version and optional backends, profiles, and prompts mappings. Collection release labels are descriptive, with no SemVer ordering or dependency-solving semantics. Metadata is optional: an installed collection can contain resources without claiming a published release.

Each resource key inside a collection is local. The parent namespace and local key follow the accepted slash-free component grammar; their public spelling is exactly namespace/local-name. There are no duplicate embedded id or namespace fields to reconcile. Dots remain ordinary characters.

To retain unqualified application resources, recommend optional root-level backends, profiles, and prompts mappings, also keyed by local name and 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.

Stored references such as default_profile, profile backend, and smoke-test profile defaults remain exact public references. Nesting does not automatically qualify a slashless reference or rebind it to caller scope. For example, a profile in provider still declares backend: provider/default. Caller-scoped lookup follows the existing namespace roadmap after final indexes are built.

One Installed Prompt And Optional Version

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.

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 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.

Required ConfigKit Mount Semantics

The upstream feature should be generic source placement, not a PromptKit-aware collection loader or application callback that transforms source documents. The following is the recommended contract to agree and test upstream:

1. An input has an optional destination of literal mapping-key segments. An empty destination preserves existing root behavior. It is independent of the filesystem path, filesystem containment root, and precedence group.
2. ConfigKit parses each source with its existing YAML rules and processes source-root directives before placing application content at its destination. 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 by stripping a source header. Agree its interaction with imports and main's version protection explicitly. Mounting main away from the root is unnecessary for this PromptKit standard.

Composition And Overrides

Different collection keys prevent accidental collisions between equal local resource names. Two sources targeting the same namespace are not automatically invalid: disjoint mapping contributions combine. Overlapping scalar fields, message sequences, nulls, and equal release labels conflict within a strict group. Across deliberate layers they follow ordinary precedence instead.

A higher-layer prompt mapping is a partial override. Changing only its version does not replace its messages or other settings. Omitting a field retains its lower value, and an empty mapping does not clear a definition. Publishers and operators must treat such changes as configuration customization, not as an atomic installation of another prompt release. Do not introduce source audits or a version-triggered replacement rule to conceal this distinction.

Inheritance

Existing sibling inheritance remains useful within each collection's resource mapping: extends: brief can name the local profile brief. Prompt versions, now ordinary optional fields, would inherit and overlay like other fields; version: null explicitly clears an inherited label.

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.

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.

Specification Versions And Collection Inventory

Keep version: 1 at the application root for the candidate PromptKit 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. A mounted collection.yml containing a release version does not declare or validate a separate specification version. A self-contained collection entry document with its own specification header would need a further ConfigKit contract for checking and consuming that header before mounting its payload. Do not infer compatibility from a directory name or release label, or have PromptKit load and validate each manifest separately. Keep that upstream extension open rather than bundling it implicitly into source placement.

Recommend collection inventory derived from the final collections mapping: 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 package identity, historical source ownership, or proof of unchanged published contents. Operator overrides may alter resources while leaving a release label in place. Source explanations remain ConfigKit inspection concerns. Engine construction captures configuration; edits require a replacement engine.

Comparison And Migration

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
Main upstream change	None	Record composition and inheritance	Source placement, provenance, and adjusted path protection
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

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.

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. 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. This is a breaking configuration/API change under the release policy; implementation must include consumer migration guidance and update current contracts when it lands. The proposal does not change today's supported configuration or API.

Delivery, Validation, And Remaining Decisions

Agree and implement the generic mount contract in ConfigKit first, then adopt it in PromptKit's source helpers and final-configuration adapter. Build qualified runtime indexes only after handoff. Keep collection installation, remote fetching, automatic directory discovery, live reload, and dependency solving outside this work.

Upstream acceptance should exercise root and nested placement; overlapping destinations within strict groups and across layers; mounted nested imports; source cycles/repetition; destination-aware protected-version checks; source locations and resource bases; sibling inheritance; and unchanged unmounted behavior. Verify mounted metadata cannot bypass root version protection.

PromptKit acceptance should cover the illustrated assembled tree, same local names in different collections, unqualified resources, scoped selection, versioned and unversioned prompts, explicit version assertions if retained, inventory without release metadata, source-relative message content, and intentional partial overrides. Do not add per-source PromptKit validation.

Review verification on 2026-10-14: a temporary offline consumer of the local 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:

• Mount API and packaging: prefer an input destination plus a conventional explicitly selected directory layout. An import-destination directive would let publishers express more assembly in configuration; settle its syntax upstream. A manifest that computes its own mount from a declared namespace would require further ConfigKit semantics and is not assumed here.
• Cross-collection inheritance: prefer existing local sibling inheritance initially; add generic path references upstream if migration needs justify the added contract.
• Request versions: prefer optional exact assertions for migration; removing version selectors is simpler if consumers do not need that guard.
• Independent specification headers: keep one main-owned declaration for this proposal; pursue a distinct ConfigKit extension if collections must each assert compatibility independently.

These recommendations are reviewable choices, not claims that upstream work has been accepted. One installed definition and an optional prompt version are the settled requirements for this alternative. The parent configuration decision remains open while the three proposals are compared.