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

Retire unselected collection configuration proposals

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-16 11:59:34 +00:00
parent b5866dd749
commit 190ec69345
4 changed files with 88 additions and 939 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/roadmap/namespaces.md
View File

@@ -3,9 +3,10 @@
Status: feature roadmap; not implemented. The reserved-slash naming convention,
reference-resolution rules, decisions 1–3 (scope shape, validation, and integrated
discovery filtering), and decision 4's move to application/operator-supplied
configuration are accepted target behavior. Collection metadata, inventory, and
specification-version integration remain pending in decision 5, subject to the
ConfigKit boundary. Exact Go names and option types remain delivery details.
configuration are accepted target behavior. Decision 5 selects mounted collections
and shared source-version checking; its remaining policy and API choices are
tracked in the collection roadmap, subject to the ConfigKit boundary. Exact Go
names and option types remain delivery details.
## Purpose
@@ -82,8 +83,9 @@ A profile ID identifies execution settings. Its configured model value is
still the identifier passed to the provider; qualifying the profile ID does
not modify that value. Both example profiles may retain the configured model
`google/gemma-4-31b-it`. Different profiles may select the same model with
different settings. Prompt versions also remain separate from namespaces and
continue to use the existing selection rules.
different settings. Prompt version labels remain separate from namespaces. The
selected collection format installs one definition per prompt ID; optional
request-version handling remains a decision in the collection roadmap.
Retain unqualified and dotted IDs. Existing slash-containing IDs need review:
those with one slash and nonempty components become qualified identities, while
@@ -135,8 +137,8 @@ The accepted resolution rules, independent of the final scope API, are:
Keep qualification consistent across execution, preparation, request validation,
prompt/profile inspection, and applicable smoke-test selections. Namespace
selection must not change request override precedence, prompt version selection,
or provider model strings.
selection must not change request override precedence, the chosen request-version
semantics, or provider model strings.
### Local And Qualified References In One Operation
@@ -288,11 +290,11 @@ follow the eventual decision 5:
and all-namespaces filters override that default for the current listing only.
- A valid namespace with no matches produces an empty listing. Namespace
filtering respects resource type and exact namespace boundaries.
- Existing exact-ID calls using valid IDs, intentional overlays, and prompt
versions retain their behavior. Migrated catalog references resolve to their
intended resources without collisions.
- Listings preserve full IDs and separate prompt versions. Qualified results
round-trip through either engine or view; unqualified results round-trip
- Exact-ID calls using valid IDs and intentional overlays retain their behavior.
Migrated catalog references resolve without collisions; the collection roadmap
owns migration to one installed prompt and optional version labels.
- Listings preserve full IDs and separate optional prompt version labels.
Qualified results round-trip through either engine or view; unqualified results round-trip
through the engine without a corresponding scope.
- Representative validation, inspection, execution, and smoke-test paths use
the same qualification rules without duplicating every test at every layer.
@@ -410,9 +412,10 @@ with no matching resources returns an empty listing. Represent default, named,
unqualified-only, and all-namespaces selections distinctly in the API; do not
overload an empty string to mean several of them.
Return full IDs, retaining prompt versions as separate identity fields. Do not
invent a named namespace such as `default` for unqualified resources. Namespace
enumeration excludes that unnamed group. Use deterministic ordering consistent
Return full IDs with optional prompt version labels separately; the full ID
identifies the installed prompt. Do not invent a named namespace such as `default`
for unqualified resources. Namespace enumeration excludes that unnamed group.
Use deterministic ordering consistent
with existing listing contracts.
Qualified result IDs can be passed unchanged to either scoped or unscoped
@@ -485,89 +488,35 @@ dependencies instead.
### 5. Collection Metadata And Specification Versioning (Open)
[Proposal 1: current ConfigKit](configuration-collections-current-configkit.md)
develops a concrete configuration standard for the existing composition rules.
[Proposal 2: identified records](configuration-collections-identified-records.md)
uses an opt-in upstream extension for identity-based record composition and
inheritance. [Proposal 3: mounted fragments](configuration-collections-mounted-fragments.md)
uses explicit upstream source placement and collection-local mapping keys,
with one installed definition per prompt and an optional flat version field.
Proposal 3 now targets implemented ConfigKit development-branch capabilities,
including relative imports and shared source-version checks with `IfPresent`. It
uses `release_version` for collection metadata; proposals 1 and 2 preserve their
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.
**Selected direction: [mounted collections](configuration-collections-mounted-fragments.md).**
Proposal 3 is the active configuration roadmap. It uses collection-local mapping
keys, one installed definition per prompt, and an optional flat prompt version.
Input destinations, relative imports, and shared source-version checks are
implemented in ConfigKit's reviewed development branch. PromptKit still needs
to adopt a suitable dependency release and implement its new schema.
**Desired capability:** describe collection namespace and release version in
configuration and expose an API through which downstream applications can list
effective collection declarations captured by an engine. A collection release
version is distinct from an individual prompt version and from the PromptKit
software version. Use top-level `version: 1` for PromptKit specification version
1, following ConfigKit's version mechanism, rather than introducing a
`promptkit_spec` field. The ownership and placement of that version declaration
across multiple sources remain part of this open decision.
Use shared specification checking with `IfPresent` and distinct collection
`release_version` metadata. Collection entries can describe their layout through
relative imports; applications select their sources and namespaces. PromptKit
interprets the final collection/resource keys as qualified IDs after ConfigKit's
handoff. It adds no manifest pre-parser, source-level namespace ownership rule,
or history-based validation pass. Stored references remain exact public IDs.
The initially discussed root manifest contained `collection.namespace` and
`collection.version`. That shape and a standard manifest filename are not
settled. In particular, the proposal to load/check each manifest separately in
PromptKit before composing definitions is withdrawn. PromptKit must respect the
ConfigKit boundary described above, including for version checks and duplicate
declarations.
Proposals 1 and 2 were not selected and have been retired. Their original
contents and the separately preserved ConfigKit identified-record request are
recorded in the collection roadmap's
[retirement note](configuration-collections-mounted-fragments.md#retired-alternatives-and-upstream-request).
The record-sequence request is independent future upstream work and does not
block the selected mapping design.
ConfigKit v0.7.1's layered-loading contract checks the configured application
version path on the main input only. Underlay roots cannot claim that path,
and imported fragments cannot independently declare it. ConfigKit supplies the
version mechanism while the application defines supported specification values;
this does not give PromptKit permission to implement an independent collection
assembly or compatibility-checking pass.
The collection roadmap owns the candidate schema, examples, version policies,
metadata inventory, and migration requirements. Inventory describes effective
collection declarations captured by the engine, not historical manifests or
proof of unchanged published releases. Source explanation remains ConfigKit's
inspection concern.
**Recommended starting point, pending decision: ordinary ConfigKit composition
with collection metadata in final effective values.** For example, the main
configuration could own `version: 1`, with a namespace-keyed collection mapping:
```yaml
version: 1
collections:
openrouter:
version: "2026.10.13"
weatherreporter:
version: "2.4.0"
```
This is a candidate shape, not an implemented or accepted schema. Other sources
could contribute to `collections` without claiming the main version field.
ConfigKit would decide whether contributions conflict or combine; PromptKit
would interpret and validate only the final metadata. A namespace key would
identify one effective entry without requiring a source-level uniqueness rule.
It would not automatically qualify definition keys or stored references.
This approach reuses the existing composition contract and avoids a parallel
manifest loader. Its limitation is that it does not independently check a
specification declaration for each imported collection. An effective declared
release version also does not prove that every resource still matches that
release after operator overrides.
**Alternative: add collection/import compatibility support within ConfigKit
before adopting independently versioned collection roots.** If every collection
must declare its own specification version, design that capability in ConfigKit,
including how versions and metadata interact with imports and layers. PromptKit
would consume its resulting handoff and diagnostics. This could provide useful
per-collection compatibility checks without violating ownership, but it expands
the work into ConfigKit and requires a supported contract there before PromptKit
can depend on it. No ConfigKit change is selected by this roadmap yet.
Under either approach, the inventory should describe effective collection
metadata captured at engine construction, not reconstruct a historical list of
loaded manifests. Source contributions and explanations remain ConfigKit
inspection concerns. Inventory should not reread installed files or claim that
declared versions prove unmodified published contents. Namespace enumeration
from resource IDs remains independent of this metadata API.
**Pending question:** is ordinary composed collection metadata with one main
specification declaration sufficient, or are independently version-checked
collection roots essential enough to warrant ConfigKit work? Settle that before
finalizing metadata schema, root-file conventions, inventory API values, or
collection compatibility rules. Removal of bundled catalogs and built-in
profiles remains accepted in either case.
**Still open:** the [six remaining PromptKit decisions](configuration-collections-mounted-fragments.md#remaining-promptkit-decisions)
cover main declaration requirements, exposing stricter checking, resources named
`version`, request-version assertions, cross-collection inheritance, and consumer
APIs/packaging. Selecting proposal 3 and retiring its alternatives does not settle
those choices. Removal of bundled catalogs and built-in profiles remains accepted.